echo6-docs/docs/navi/cc-rules.md

Navi: Claude Code Rules

Repository & SSH

All Navi SSH goes to: recon-vm (VM 1130, 192.168.1.130)

Never SSH to cortex for Navi work. Previous attempt to deploy from cortex wrecked production by deploying from a stale clone.

Work directory: /home/zvx/projects/repos/navi on VM 1130

Never touch: /home/zvx/projects/navi-work on cortex (stale clone, do not use)

Critical Constraints

• Never re-export namedTheme through any intermediary module — import directly from protomaps-themes-base in MapView.jsx
• Never use git add -A — stage files explicitly
• Never deploy without smoke tests — run full checklist (see deployment.md)
• Never start preview servers — deploy to production and test there

Build & Deploy

ssh recon-vm
cd /home/zvx/projects/repos/navi
npm run build && rsync -av --delete dist/ /mnt/nav/frontend/

Git Workflow

• Feature branches: name descriptively (theme-, fix-, feat-*)
• Always merge to master before deploying
• Check for unmerged commits: git log branch..master --oneline

Code Patterns

queryRenderedFeatures for Optional Layers

Guard with map.getLayer() — USFS/BLM hit layers may not exist:

const layers = [USFS_TRAILS_HIT, USFS_ROADS_HIT].filter(id => map.getLayer(id))
const features = layers.length > 0
  ? map.queryRenderedFeatures(e.point, { layers })
  : []

buildStyle Theme Colors

const theme = getTheme(themeName)
const colors = theme.colors || namedTheme(themeName)  // direct import

PlaceCard useEffect Changes

Investigation-before-implementation — fragile race conditions between:

• Boundary fetch from Wikidata/OSM
• selectedPlace state updates
• AbortController cleanup

Architecture Notes

• Boundary highlight is NOT an overlay toggle — it's a dynamic click-response layer
• Route polyline uses GeoJSON source.setData() — silent failure if namedTheme is re-exported
• Measure tool also uses GeoJSON — same failure mode

Smoke Test Checklist

After every deploy:

• Route between two addresses — polyline renders
• Click city label — boundary outline appears
• Theme switching (all 4 themes)
• Overlay toggles (hillshade, contours, public lands)
• Console: no "bt is not defined" or "f is not defined"