fix: authenticate the CARTO basemaps with the suite key

[tgilbert14]

What

Canary PR — first of nine. CARTO began watermarking unauthenticated basemaps.cartocdn.com raster tiles with "API KEY REQUIRED" on 2026-08-26, so both maps here — the national site-picker and the theme-aware Biogeography map — render defaced. The request still returns HTTP 200 with a valid PNG, so nothing errored or logged. Full suite diagnosis: docs/SUITE-BASEMAP-INCIDENT-2026-08.md in NEON-Driver-Cascade and tgilbert14/NEON-Driver-Cascade#70.

How

Adds add_suite_basemap() to global.R and routes both call sites through it (R/map_picker.R:57, server.R:1633-1634):

• With CARTO_BASEMAP_KEY set (Connect Cloud content variable, already issued by CARTO and verified against live tiles): the exact same Positron / Dark Matter tiles as before, keyed. addProviderTiles() cannot carry the key — the bundled CartoDB template has no {apikey} placeholder — so it is a raw addTiles() with explicit OpenStreetMap + CARTO attribution.
• Without the key: falls back to Esri's keyless grey canvas (light and dark variants) so the map degrades to a clean basemap, never a defaced one. Capped at maxNativeZoom = 16 because that canvas has no content past z16 at rural NEON sites.
• The dark-mode toggle keeps working unchanged: is_dark() now selects dark_all through the same helper.

The key is a public, rate-limited identifier, not a credential — it rides in the client-side tile URL by design (CARTO's terms ban server-side proxying). The env var keeps it out of git and makes rotation a Connect setting rather than a release.

Manifest

manifest.json is intentionally untouched in the first commit — AGENTS.md rule 2 says never edit it by hand, and this repo has no regenerate-manifest.yml dispatch workflow. The first CI run regenerates it in the pinned validator and uploads the validated manifest candidate artifact; the follow-up commit lands exactly those bytes. Expect the first run red at "Require committed generated bytes to match" — that is the plan working, not a failure of the patch.

Before merging (owner)

1. Connect Cloud → this app's content settings → Variables → add CARTO_BASEMAP_KEY with the key CARTO emailed (starts cb1_…). Until it is set, the deployed app shows the clean Esri fallback rather than CARTO.
2. Merge (a human-reviewed merge is the production decision), then check the live map: picker shows Positron, dark mode shows Dark Matter, no watermark, attribution visible.

Verified

• The key returns clean tiles where unkeyed requests are watermarked — proven at CDN origin misses for light_all and dark_all, and on the previously-cached watermarked picker zooms (the CDN caches keyed responses separately).
• grep -E 'CartoDB[."$]|cartocdn' across the repo: no unkeyed CARTO reference remains.
• git diff --check clean; helper parens/braces balanced. No R interpreter was available in the patch environment, so CI's offline-source step is the syntax gate.

🤖 Generated with Claude Code

https://claude.ai/code/session_01738HeGPEU9NEoczL8RXnu1

---

Generated by Claude Code