---
title: STARTER KIT — COMMON MODIFICATIONS
slug: starter-kit-modifications
layer: STARTER KIT
layer_order: 8
order: 108
description: Recipes for the changes operators ask for — each with what to change, where, the invariant to respect, and an acceptance test.
---

> **FLUX DOCUMENTATION SYSTEM**
> Layer 11 — STARTER KIT | starter-kit-modifications
> flux.dantesisofo.com/wiki/starter-kit-modifications/

# STARTER KIT — COMMON MODIFICATIONS

Each recipe: **WHAT → WHERE → VERIFY.** After any change that affects public
surfaces, re-run `deploy_surfaces` + invalidate, or re-publish an affected project.
Respect the invariants in [DEPLOYMENT §5](../starter-kit-deployment/).

---

## 1. NAME A NEW CITY / BRAND
**WHAT:** set the brand + hub tag. **WHERE:** `.env` — `COLLECTION`, `FLUX_AUTHOR`,
`FLUX_BASE_URL`; titles already derive from `canonical()`. **VERIFY:** new projects
get `collections=[COLLECTION]` and appear on the hub.

## 2. RETARGET COVERAGE
**WHAT:** change the "N / TARGET corridors" goal. **WHERE:** `.env` `CORRIDOR_TARGET`.
**VERIFY:** hub + embed coverage % = `round(100*n/TARGET)`; rebuild surfaces.

## 3. RECOLOR ROUTES
**WHAT:** change the route accent. **WHERE:** `.env` `ROUTE_COLOR` (used by project
page + hub + embed map line). Keep hover a darker shade. **VERIFY:** map polylines
use the new hex; coverage bar/accent still consistent.

## 4. CHANGE MAP TILES
**WHAT:** different basemap. **WHERE:** `.env` `TILE_URL` (Leaflet template). **VERIFY:**
tiles load on project page, hub, embed; attribution updated.

## 5. SWITCH DISPLAY UNITS (MILES ↔ KM)
**WHAT:** public distance unit. **WHERE:** the single distance formatter used by all
builders. **INVARIANT:** storage stays `distance_km`; convert only at render.
**VERIFY:** hub == embed == project page show the same converted value.

## 6. ADD A HUB STAT
**WHAT:** new aggregate (e.g. "cameras used"). **WHERE:** ensure the field exists per
WalkRecord (add in publisher §5 from `submission.stats`), then add a `.stat` cell in
`build_hub` (and embed if desired). **VERIFY:** value equals the catalog aggregate.

## 7. ADD A FIELD TO THE ROUTE POPUP
**WHAT:** show e.g. camera/lens in the map popup. **WHERE:** add the field to the
`map_walks` objects in `build_hub`/`build_embed`, then into the popup HTML. **VERIFY:**
clicking a route shows the new field; OPEN PROJECT still `target="_top"`, monochrome.

## 8. HIDE A PROJECT FROM A LISTING (NO DELETION)
**WHAT:** keep a project live by URL but off a browse listing. **WHERE:** filter by
`collections` in the relevant builder (e.g. `build_catalog_index` excludes
`COLLECTION`; to hide one project from the hub, remove its tag or add an allowlist).
**INVARIANT:** never delete data; this is a *listing filter only*. **VERIFY:** project
URL still 200; it's absent from the chosen listing.

## 9. NORMALIZE TITLES / CASING
**WHAT:** enforce `STREET_NAME_IN_FLUX` everywhere. **WHERE:** `canonical()` is the
authority; for already-published projects, patch `catalog.title` + the project page
title slots + regenerate surfaces. **INVARIANT:** changing a **title** is safe;
changing a **slug** changes the URL → needs a redirect (see #12). **VERIFY:** hub,
project page, and embed all show the canonical title.

## 10. CHANGE DERIVATIVE SIZE / CONTACT SHEET
**WHAT:** larger web images or denser contact sheet. **WHERE:** Worker stage 4
(derivative long-edge/quality) and stage 9 (grid columns). **VERIFY:** re-generate a
draft; `large/` images at new size; contact sheet renders.

## 11. SWAP THE GEOCODER
**WHAT:** different reverse-geocoding provider. **WHERE:** Worker stage 5 — keep the
contract: `(lat,lon) -> address|None`, rate-limited, **grid-cached**, never fatal.
**VERIFY:** addresses resolve; failures degrade to raw coords, not crashes.

## 12. RENAME A SLUG (URL CHANGE) — CAREFUL
**WHAT:** change a live project's URL. **WHERE:** server-side copy `s3 <old>/* →
<new>/*`; update `catalog` (`slug`,`public_url`,`cover_image`); tombstone old slug;
write a **redirect stub** at the old `index.html` (CloudFront+OAC does not honor S3
website redirects). **VERIFY:** old URL redirects, new URL 200, hub points to new.

## 13. ADD AN OG/SOCIAL IMAGE TO PROJECT PAGES
**WHAT:** rich link previews. **WHERE:** `build_project_page` head — add
`og:image` = `FLUX_BASE_URL/<cover_image>`. **VERIFY:** meta tag present; image 200.

## 14. ADD A NAV ITEM ACROSS ALL PAGES
**WHAT:** a new top-nav link. **WHERE:** the nav source/template used by every
builder. **GOTCHA:** if any pages are static and deployed via `s3 sync`, patch the
**local source**, not just live S3 — a later sync overwrites live with stale local.
**VERIFY:** the item appears on every page type after rebuild + deploy.

## 15. STORE AI-TRAINING LINEAGE (FUTURE)
**WHAT:** record `ALL_PHOTOS` (every imported frame), `PUBLISHED_PHOTOS` (kept),
`ZINE_PHOTOS` (final selection) per project to learn editing behavior later.
**WHERE:** write a `lineage` block into `submission.json` + a private (non-public)
copy; populate from the edit actions; never expose publicly. **VERIFY:** lineage
captured automatically on edit/publish; not in any public surface.

---

## GENERAL RULE FOR ANY MODIFICATION
1. Change the **single source** (config or the one builder/function).
2. Respect invariants ([OVERVIEW §5](../starter-kit-overview/)): canonical naming,
   hub+embed together, route-only hub, no-cache HTML, EXIF-stripped images.
3. **Rebuild + invalidate**; verify the public surface.
4. Never delete project data to change presentation.

---

FLUX_WIKI_v2.0 — flux.dantesisofo.com/wiki/starter-kit-modifications/