# Hell Let Loose Field Manual — Polish and Expansion Plan

> **For Hermes:** Use `static-guide-enhancement-batch` for static-site implementation batches. For large coding passes, use `subagent-driven-development` task-by-task with verification after each batch.

**Goal:** Turn the completed Hell Let Loose Field Manual from a strong static guide into a polished, highly usable second-screen field tool with deeper doctrine, better UX, accessibility, performance, and maintainable data.

**Architecture:** Keep the site fully static under `/var/www/html/hll`. Prefer small HTML/CSS/JS enhancements, data-driven rendering from existing `assets/*.js` files, localStorage for personal state, and idempotent generation scripts for repeated page furniture. Avoid a backend unless a future requirement truly needs server state.

**Tech Stack:** Static HTML, CSS, vanilla JavaScript, localStorage, browser verification, Node syntax checks, Python static link/fragment validation.

---

## Priority 0: Stabilize and polish the current completion pass

### Task 1: Turn completion state into a visible “what changed” changelog

**Objective:** Add a concise changelog page so users can see recent additions and know what is patch-sensitive.

**Files:**
- Create: `/var/www/html/hll/changelog.html`
- Modify: `/var/www/html/hll/index.html`
- Modify: `/var/www/html/hll/assets/app.js`
- Modify: `/var/www/html/hll/assets/site.css`

**Steps:**
1. Create `changelog.html` using the same page-hero/nav/footer pattern as other pages.
2. Add entries for Batch A, full-plan completion, map layers, tank engagement helper, Beginner Mode, and My Field Kit.
3. Add a small homepage card linking to the changelog.
4. Add `Changelog` to the search index terms.
5. Verify `changelog.html` has valid nav, route footer, and no missing assets.

**Verification:**
- `node --check assets/app.js`
- Static link/fragment check.
- Browser navigate to `/changelog.html` and inspect console.

### Task 2: Audit and polish Beginner Mode behavior

**Objective:** Make Beginner Mode feel intentional instead of only hiding/flagging advanced sections.

**Files:**
- Modify: `/var/www/html/hll/assets/app.js`
- Modify: `/var/www/html/hll/assets/site.css`
- Touch pages only if static callout anchors are needed.

**Steps:**
1. Add a visible Beginner Mode explainer panel near the top of each major page when active.
2. Add page-specific “Do this next” bullets for Home, Guide, Roles, Tanking, Maps, Artillery, and Checklists.
3. Ensure advanced sections collapse consistently without hiding core navigation.
4. Add a quick way to turn Beginner Mode off inside the panel.
5. Verify persistence across pages.

**Verification:**
- Browser: toggle Beginner Mode on Home, navigate to Tanking and Maps, confirm panel persists.
- Console clean.

### Task 3: Polish responsive/mobile layout after added controls

**Objective:** Prevent crowding from new nav buttons, map toggles, doctrine toggles, and tank helper dropdowns on phones.

**Files:**
- Modify: `/var/www/html/hll/assets/site.css`

**Steps:**
1. Test key pages at narrow widths via browser visual QA.
2. Stack map toggles into a two-column chip grid on small screens.
3. Make tank engagement fields one-column below 700px.
4. Improve sticky mobile utility bar spacing with safe-area padding.
5. Ensure no button rows overflow horizontally.

**Verification:**
- Browser visual QA on Home, Maps, Tanking.
- Run console check after interactions.

---

## Priority 1: High-value tactical expansion

### Task 4: Add a “Squad Leader Academy” focused guide section

**Objective:** Create a deeper SL learning path beyond copy cards: OP cadence, garrison judgment, orders, defense calls, and squad psychology.

**Files:**
- Modify: `/var/www/html/hll/playbook.html`
- Modify: `/var/www/html/hll/assets/site.css`
- Modify: `/var/www/html/hll/assets/app.js`

**Sections to add:**
1. First 3 minutes as SL.
2. OP placement patterns: aggressive, safe, recovery, defensive.
3. When to ask Support vs truck vs commander drop.
4. How to give one clear order.
5. Defensive squad checklist.
6. What to say when the squad ignores you.

**Verification:**
- Search for “SL academy”, “OP cadence”, “defensive squad”.
- Visual QA playbook page.

### Task 5: Add Commander resource and ability timing cards

**Objective:** Expand Commander guidance with practical resource triage and ability timing.

**Files:**
- Modify: `/var/www/html/hll/playbook.html`
- Modify: `/var/www/html/hll/assets/site.css`

**Sections to add:**
1. Opening logistics script.
2. Node dependency and resource priorities.
3. Supply drop vs supply truck vs airhead decision guide.
4. Bombing run / strafing / reinforce / encouraged timing notes.
5. Recovery play when the team loses multiple garrisons.

**Verification:**
- Copy cards still work.
- Playbook remains readable in Quick/Full toggles.

### Task 6: Add anti-tank and engineer mini-schools

**Objective:** Give AT and Engineer their own practical doctrine blocks, not just role summaries.

**Files:**
- Modify: `/var/www/html/hll/roles.html`
- Modify: `/var/www/html/hll/checklists.html`
- Modify: `/var/www/html/hll/assets/roles.js`

**Sections to add:**
1. AT: tank marking, flank routes, rocket discipline, AT gun use, satchel safety.
2. Engineer: node routes, mine placement, repair stations, fortification judgment.
3. Add tags to role filters for “vehicle counter”, “build economy”, and “defensive utility”.
4. Add checklists for AT and Engineer advanced play.

**Verification:**
- Role filters still return correct counts.
- Checklist persistence still works.

---

## Priority 2: Map room upgrades

### Task 7: Make tactical overlays more map-specific

**Objective:** Replace generic synthetic route lines with per-map tuned route presets where practical.

**Files:**
- Modify: `/var/www/html/hll/assets/maps.js`
- Modify: `/var/www/html/hll/assets/site.css`

**Steps:**
1. Add optional `routePresets` keyed by map key.
2. Start with high-value maps: Foy, Remagen, Purple Heart Lane, Carentan, Kursk, Omaha.
3. For each map define attack routes, safer flanks, armor danger lanes, and likely garrison zones.
4. Fall back to synthetic routes for maps without tuned data.
5. Add tooltip labels for each route.

**Verification:**
- Marker/layer counts differ by map.
- Lightbox stays synchronized with base map.
- CSS positions routes and zones correctly.

### Task 8: Add map comparison cards

**Objective:** Help beginners choose behavior by terrain type and compare maps quickly.

**Files:**
- Modify: `/var/www/html/hll/maps.html`
- Modify: `/var/www/html/hll/assets/maps.js`

**Features:**
1. Terrain family filter: urban, forest, open, bridge, bocage, desert.
2. “Hard for beginners” badge.
3. “Armor impact” badge.
4. “Arty pressure” badge.
5. Quick link to selected map in the map room.

**Verification:**
- Filters are combinable with map select or independent without breaking select.
- Search index includes terrain family terms.

### Task 9: Add map-specific spawn mistake cards

**Objective:** Make map warnings more concrete by listing common bad spawns and better alternatives.

**Files:**
- Modify: `/var/www/html/hll/assets/maps.js`
- Modify: `/var/www/html/hll/maps.html`

**Examples:**
- Foy: “Do not spawn open-field garry and sprint straight in; use smoke/ditch route.”
- Remagen: “Do not feed bridge from one spawn; build side/high-ground pressure.”
- PHL: “Do not cross flooded fields alone; move ditch-to-ditch.”

**Verification:**
- Selected map updates mistake cards.
- Beginner Mode emphasizes mistake cards.

---

## Priority 3: Tanking expansion

### Task 10: Upgrade tank engagement helper with crew-call outputs

**Objective:** Make the helper produce copyable crew and command-channel callouts.

**Files:**
- Modify: `/var/www/html/hll/assets/tanks.js`
- Modify: `/var/www/html/hll/tanking.html`

**Features:**
1. Crew callout: clock/range/action phrasing.
2. Command callout: grid/facing/class phrasing.
3. “If ricochet” follow-up.
4. “If tracked” follow-up.
5. Copy buttons for each output.

**Verification:**
- Copy buttons restore text and do not use blocking prompts.
- Representative matchups produce sensible outputs.

### Task 11: Add tank weak-angle visual mini-diagrams

**Objective:** Explain front/side/rear threat visually without pretending to be exact damage tables.

**Files:**
- Modify: `/var/www/html/hll/tanking.html`
- Modify: `/var/www/html/hll/assets/site.css`

**Features:**
1. Top-down tank silhouette diagram.
2. Front danger zone, side opportunity, rear/engine opportunity.
3. Ricochet angle warning.
4. Kiting/reverse path diagram.

**Verification:**
- Visual QA at desktop and mobile widths.
- Print mode remains readable.

### Task 12: Add tank crew practice drills

**Objective:** Help armor crews train communication and seat discipline.

**Files:**
- Modify: `/var/www/html/hll/tanking.html`
- Modify: `/var/www/html/hll/checklists.html`

**Drills:**
1. Driver stop/reverse/angle drill.
2. Gunner target ID drill.
3. Commander scan/mark drill.
4. Repair under cover drill.
5. Disengage decision drill.

**Verification:**
- Checklists support drill completion.
- Tanking page links to drill checklist.

---

## Priority 4: Content depth and trust

### Task 13: Add “sources and patch notes” page

**Objective:** Centralize source confidence, community-derived data, and patch-sensitive warnings.

**Files:**
- Create: `/var/www/html/hll/sources.html`
- Modify: nav/search/route footers.

**Sections:**
1. What is stable doctrine.
2. What is patch-sensitive.
3. What is community-derived.
4. Suggested update checklist after a new HLL patch.
5. Credits/disclaimers.

**Verification:**
- Link from update strips and footer.
- Search terms include “source”, “patch”, “version”, “current”.

### Task 14: Add content QA checklist for future updates

**Objective:** Make future site maintenance repeatable.

**Files:**
- Create: `/var/www/html/hll/maintenance-checklist.md`

**Checklist:**
1. JS syntax checks.
2. Link/fragment checks.
3. Browser interaction checks.
4. Console checks.
5. Visual QA pages.
6. Patch-sensitive content review.
7. Cache-busting procedure.

**Verification:**
- File exists and is linked from `sources.html` or plan docs if appropriate.

### Task 15: Improve SEO/internal linking without keyword stuffing

**Objective:** Improve discoverability while keeping the manual readable.

**Files:**
- Modify major HTML pages.
- Modify JSON-LD if present.

**Steps:**
1. Add concise FAQ blocks where missing.
2. Add cross-links from related sections.
3. Add alt text review for tank/map images.
4. Add descriptive headings for tools.
5. Keep copy natural and useful.

**Verification:**
- Static link check.
- Browser spot-check rendered FAQ/details.

---

## Priority 5: Accessibility, performance, and maintainability

### Task 16: Accessibility pass

**Objective:** Improve keyboard, screen-reader, contrast, and focus behavior.

**Files:**
- Modify `/var/www/html/hll/assets/site.css`
- Modify JS files where controls need ARIA state.
- Modify HTML only for missing labels/headings.

**Checks:**
1. All buttons have accessible names.
2. Dynamic results use `aria-live` where useful.
3. Focus is restored after overlays/lightboxes close.
4. Keyboard operation works for search, map lightbox, tank lightbox, filters.
5. Contrast is acceptable for brass/red text on paper.

**Verification:**
- Browser keyboard walkthrough.
- Console clean.

### Task 17: Performance and asset audit

**Objective:** Keep the static site fast despite added images and JS.

**Files:**
- Inspect assets under `/var/www/html/hll/assets`.
- Modify HTML image loading attributes if needed.

**Steps:**
1. List asset sizes.
2. Identify oversized images.
3. Ensure non-hero images use `loading="lazy"`.
4. Defer noncritical scripts where safe.
5. Confirm cache-busted asset versions are consistent.

**Verification:**
- Static asset report saved to `/var/www/html/hll/performance-notes.md`.
- Browser load has no missing images/scripts.

### Task 18: Convert repeated page furniture to a generation script

**Objective:** Reduce manual drift in nav, footer, update strips, and route footers.

**Files:**
- Create: `/var/www/html/hll/tools/generate-page-furniture.py`
- Modify: static HTML pages after script generation.

**Steps:**
1. Define page map with title, previous, next, related, caveat type.
2. Remove existing generated blocks idempotently.
3. Reinsert nav active state, update strip, and route footer.
4. Add dry-run mode.
5. Document usage in `maintenance-checklist.md`.

**Verification:**
- Run script in dry-run and normal mode.
- Assert exactly one nav/footer/update block per page.
- Static link check.

---

## Recommended execution order

### Batch D: Polish and stabilization
1. Changelog page.
2. Beginner Mode polish.
3. Mobile/responsive polish.
4. Accessibility quick fixes.

### Batch E: Tactical depth
1. Squad Leader Academy.
2. Commander resource/ability timing cards.
3. AT and Engineer mini-schools.
4. Tank crew practice drills.

### Batch F: Map and tank power tools
1. Per-map tuned tactical overlays for key maps.
2. Map comparison cards.
3. Map-specific spawn mistake cards.
4. Tank engagement helper callout upgrades.
5. Tank weak-angle diagrams.

### Batch G: Trust, maintainability, and performance
1. Sources and patch notes page.
2. Maintenance checklist.
3. SEO/internal linking pass.
4. Performance and asset audit.
5. Page-furniture generation script.

---

## Verification standard for every batch

Run this before calling any batch complete:

1. `node --check assets/app.js`
2. `node --check assets/maps.js` if map JS changed.
3. `node --check assets/tanks.js` if tank JS changed.
4. `node --check assets/roles.js` if role JS changed.
5. Static link/asset/fragment check across HTML pages.
6. Browser interaction checks for every new/modified tool.
7. Browser console check after navigation and interactions.
8. Visual QA on at least one desktop and one mobile-sized page.
9. Cache-bust changed CSS/JS references.
10. Update this plan with completion status for the batch.


---

## Completion status — 2026-05-23 final pass

All planned batches D-G have been implemented in the static site.

- Batch D: changelog page, Beginner Mode explainer panels, mobile/responsive polish CSS, and accessibility/focus support for interactive panels.
- Batch E: Squad Leader Academy, Commander resource/ability timing cards, Anti-Tank and Engineer mini-schools, and tank crew checklist drills.
- Batch F: map-specific tactical route presets for key maps, map comparison cards, selected-map spawn mistake cards, tank engagement helper copyable crew/command/follow-up callouts, weak-angle diagrams, and crew practice drills.
- Batch G: sources/patch-notes page, maintenance checklist, SEO/internal links, performance notes, cache-busting, and a page-furniture generation scaffold.

Verification completed: JS syntax checks, static link/fragment/asset crawl after fixes, browser console checks, and visual QA spot checks.


## Batch H premium finishing pass

Implemented mobile/nav polish, Start Here onboarding, Match Emergency command palette, tank matchup/postmortem tools, tank recognition-to-action cards, high-impact map opening moves, print role pocket cards, source audit ledger, and automated QA script.