Imported from billymitchell/DJ-Nerva (AGENTS.md). Install upstream with npx skills add billymitchell/DJ-Nerva. Copyright stays with the author.

AGENTS.md

Project Overview

This repository is a static single-page marketing site for DJ Nerva. There is no app framework, bundler, or package-managed build pipeline in the repo. The site is driven by:

• index.html for page structure and most copy
• simplified-style.css for all styling and responsive behavior
• main.js for runtime hero randomization, dynamic theme colors, and gallery rendering
• JSON files in the repo root for content that is fetched client-side

The site can be previewed by opening index.html, but a local static server is safer because several features rely on fetch() for JSON files.

Recommended local preview:

python3 -m http.server 5500

Then open http://localhost:5500/.

Runtime Model

Main page flow

index.html loads:

• main.js
• places-map.js

At runtime, main.js:

1. Fetches image_data.json and taglines.json
2. Picks one image set and one tagline at random
3. Updates the hero image and CSS custom properties
4. Recolors SoundCloud embeds to match the chosen theme
5. Loads gallery_images.json on window.load and builds the photo grid

places-map.js:

• Fetches places_played.json
• Initializes the Google map if the #places-map container exists
• Adds venue markers
• Persists map center/zoom to localStorage

No framework assumptions

Do not introduce React, build tooling, or a module system unless explicitly asked. The current site is plain HTML/CSS/JS and is easy to deploy as static files.

Source Of Truth

Hand-edited files

These are the primary files agents should edit directly when changing the site:

• index.html: content, section order, embeds, map container, script tags
• simplified-style.css: visual system and layout
• main.js: hero/theme/gallery behavior
• places-map.js: Google Maps behavior
• taglines.json: rotating hero taglines
• places_played.json: venue data used by the map

Generated or script-managed files

Treat these as derived artifacts:

• image_data.json: generated by build-image-manifest.js
• gallery_images.json: generated by scripts/build_gallery_manifest.js
• soundcloud_tracks.json: generated by scripts/soundcloud_fetch.js
• mixcloud_cloudcasts.json: generated by scripts/mixcloud_fetch.js

Do not hand-edit derived JSON unless the user explicitly wants a one-off manual change.

Important HTML Conventions

Auto-managed embed regions

Inside index.html, these marker blocks are script-managed:

• <!-- AUTO-SC-START --> to <!-- AUTO-SC-END -->
• <!-- AUTO-MC-START --> to <!-- AUTO-MC-END -->

scripts/soundcloud_fetch.js rewrites the SoundCloud block. scripts/mixcloud_fetch.js rewrites the Mixcloud block.

If you need to change the structure of generated embed tiles, update the relevant script as well as the current HTML.

Gallery container

The gallery is rendered into #gallery-grid from gallery_images.json. If you remove or rename that container, update main.js.

Places map container

The venue map depends on #places-map. If you move or rename it, update places-map.js.

Data Files

image_data.json

Array of hero image sets. Each object includes:

• folder
• desktop
• mobile
• primaryColor
• secondaryColor
• accentColor

desktopPath, mobilePath, and allImages are present but only useful for maintenance scripts. Frontend runtime uses the relative filenames and color fields.

places_played.json

Object with a places array. Each place uses:

• name
• city
• lat
• lng
• link

gallery_images.json

Array of image entries with:

• filename
• path

Audio feed JSON

soundcloud_tracks.json and mixcloud_cloudcasts.json store fetched metadata and also support regenerating embed markup in index.html.

Maintenance Scripts

Hero image manifest

node build-image-manifest.js

Purpose:

• scans splash-images/<number>/
• chooses landscape image for desktop and portrait image for mobile
• extracts palette data
• rewrites image_data.json

Notes:

• This script depends on Node packages that are not declared in a package.json in this repo: image-size, node-vibrant, and chroma-js
• Avoid touching this script unless you are also prepared to validate its local dependency setup

Gallery manifest

node scripts/build_gallery_manifest.js

Purpose:

• scans DJ-images/
• rewrites gallery_images.json

Run this after adding or removing gallery photos.

Sync places from Google My Maps

node scripts/sync_places_from_google_maps.js

Purpose:

• fetches a Google My Maps KML export
• parses venues
• rewrites places_played.json
• preserves existing link values where names still match

After running it, manually verify new places and add any missing links.

Inject Google Maps API key

node scripts/inject_maps_key.js

Purpose:

• replaces YOUR_GOOGLE_MAPS_API_KEY in index.html using .env

Current repo state note:

• index.html currently loads places-map.js, but the checked-in HTML should be treated carefully around API-key changes
• .env is gitignored and should never be committed

Refresh SoundCloud embeds

node scripts/soundcloud_fetch.js

Purpose:

• fetches latest SoundCloud track metadata
• rewrites soundcloud_tracks.json
• rewrites the AUTO-SC block in index.html

Refresh Mixcloud embeds

node scripts/mixcloud_fetch.js

Purpose:

• fetches latest Mixcloud cloudcasts
• rewrites mixcloud_cloudcasts.json
• rewrites the AUTO-MC block in index.html

Operational Guidance For Agents

Prefer minimal edits

This project is mostly content and presentation. Keep changes narrow and avoid broad refactors unless requested.

Preserve the static architecture

Prefer:

• editing HTML directly for content changes
• editing CSS directly for layout and styling
• editing small JS utilities in place

Avoid introducing:

• frameworks
• bundlers
• TypeScript
• npm-based architecture changes

unless the user explicitly asks for that migration.

Be careful with stale files

These files exist but are not currently part of the active page load path:

• soundcloud.js
• mixcloud.js
• play-pause.js
• remix-reload.js

Do not assume they are active just because they exist. Check whether they are referenced from index.html before editing them.

Validate after edits

At minimum:

1. serve the repo locally
2. load the page
3. verify hero image rotation still works
4. verify gallery images render
5. verify map section does not throw console errors
6. verify SoundCloud and Mixcloud embeds still appear if you touched the music section

Deployment Notes

The _headers file suggests a static hosting platform that respects per-path cache headers. Keep that file in sync with any major asset-path or caching changes.

Because images are cached aggressively, main.js appends a cache-busting query string to hero images during runtime. Do not remove that behavior without considering stale asset issues.

Secrets

• .env is local-only and gitignored
• Never commit API keys or tokens
• If a script needs credentials, assume they belong in .env