fix: authenticate the CARTO basemaps with the suite key

[tgilbert14]

What

CARTO began watermarking unauthenticated basemaps.cartocdn.com raster tiles with "API KEY REQUIRED" on 2026-08-26. The national site-picker renders defaced on first load, and the main map does too whenever a visitor picks the "Light" basemap. 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 · tgilbert14/NEON-Driver-Cascade#70. Proven first in Ground Beetle #22 — merged, deployed, live map confirmed correct.

How

Adds add_suite_basemap() to global.R and routes all three tile call sites through it (server.R:537, :578, :588):

• With CARTO_BASEMAP_KEY set (Connect Cloud content variable): the exact same Positron tiles as before, keyed, via addTiles() — addProviderTiles() cannot carry the key because the bundled CartoDB template has no {apikey} placeholder. Explicit OpenStreetMap + CARTO attribution, as CARTO's terms require.
• Without the key: falls back to Esri's keyless grey canvas, so the map degrades to a clean basemap rather than a defaced one. Capped at maxNativeZoom = 16, that canvas's real content limit.

ui.R is unchanged. The helper accepts either a leaflet provider name or a CARTO variant, so the Basemap choices vector stays as-is and the Esri Terrain/Satellite options pass straight through to addProviderTiles() exactly as before.

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 forbids hand-editing it. 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 the byte-match gate — that is the designed flow, identical to how Ground Beetle went green.

Before merging (owner)

1. Connect Cloud → this app's content settings → Variables → add CARTO_BASEMAP_KEY (the cb1_… key). Until it is set, the deployed app shows the clean Esri fallback rather than CARTO.
2. Merge, then check the live map: picker shows Positron, "Light" shows Positron, no watermark, attribution visible.

Verified

• The key returns clean tiles where unkeyed requests are watermarked — proven at CDN origin misses (the CDN caches keyed responses separately, so a cached tile is not a valid test).
• grep -E 'CartoDB[."$]|cartocdn' finds no remaining unkeyed CARTO tile request; the only CartoDB.* strings left are the ui.R choice labels, which now route through the helper.
• git diff --check clean. No R interpreter 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

[tgilbert14]

CI is red at the manifest byte gate, and this repo exports no artifact for me to shuttle

Failing check: contracts → step 14, "Require committed generated bytes to match"
(run 33229375933)

Everything before it passed — manifest generation, verify_bundle.R, sourcing the complete app offline, and rendering a real bundled site through the Shiny server. So the R change in this PR is sound; the run only stops because manifest.json is deliberately not committed here (it must come from the pinned validator, not from me).

Why I can't complete it the way the siblings did. In Ground Beetle, Plant Diversity, Phenology, Vegetation and Small Mammal, CI uploads the validated manifest unconditionally, so I download that artifact and commit exactly those bytes — that is how Ground Beetle #22 went green and merged. This repo has only:

- name: Upload unvalidated manifest for diagnosis
  if: failure() && steps.manifest.outcome != 'skipped'

That step sits before the byte gate, so when the gate is the only failure nothing has failed yet, the upload is skipped, and the generated manifest is discarded with the runner. I confirmed the run has zero artifacts. I can't regenerate it locally either — there's no R runtime in the patch environment, and the package Built timestamps in the manifest come from the runner's own install.

To unblock, on this branch

Rscript --vanilla scripts/write_manifest.R
git commit -am "build: adopt the validated manifest for the basemap change"

Optional, and worth considering separately

Moving that upload above the byte gate and making it unconditional — as the five sibling repos already do — would let this repo self-serve a validated manifest on exactly this kind of run. I've deliberately not included that here: it's a CI change beyond what this PR is for, and it's your call.

I'll keep watching and pick this up as soon as there's a new commit.

---

Generated by Claude Code