code.json merge always lets HEAD win on overlapping keys — may serve stale Notion-generated labels

Context

Raised by @greptile-apps during PR #189 review (thread on .github/workflows/deploy-production.yml:151, comment id 3608235482), after PR #189's jq -s '.[0] + .[1]' merge fix (commit feac2e2, refined in 6f2794b) replaced the previous blind git checkout HEAD -- i18n/*/code.json restore.

The behavior

code.json mixes two categories of keys:

1. Curated theme/UI keys (~90+ keys: navbar, footer, breadcrumbs, TOC, a11y labels, etc.) — hand-maintained in this repo, never touched by the Notion pipeline. These never appear in the content branch's code.json at all.
2. Notion-generated page-title/category labels — literal English page titles used as i18n keys (e.g. "API Reference", "Building Custom Background Maps"), generated by the translation pipeline (translate-docs.yml) and committed to the content branch (TARGET_BRANCH defaults to content in that workflow), not to main.

Checked against real refs: content branch's i18n/es/code.json has 65 keys; 63 of those already exist in main's code.json (159 keys total), presumably from an earlier one-time sync/backport. Only 2 are content-only.

The current merge (jq -s '.[0] + .[1]' "$f" <(git show "HEAD:$f")) is intentionally right-biased so HEAD wins any overlapping key — this was required so this PR's own curated fixes (navbar logo.alt, 5 Spanish grammar corrections, etc.) aren't silently overwritten by whatever the content branch happens to have. But it means: for any of those 63 overlapping Notion-generated keys, if translate-docs.yml pushes a newer translation to the content branch, production keeps serving main's older, frozen copy of that key until someone manually re-syncs it into main.

Why this isn't new, and isn't blocking PR #189

This exact "HEAD wins" behavior predates PR #189 — the previous code (git checkout HEAD -- i18n/*/code.json) was 100% HEAD-wins (it dropped content-only keys entirely, which PR #189 fixed). PR #189's merge only improved the situation (content-only keys now survive); it didn't change who wins on overlapping keys, and didn't introduce this staleness risk.

Possible directions

• Split code.json conceptually: keep a repo-owned allowlist/pattern for curated theme keys (HEAD wins) vs. everything else (content wins), so Notion-generated labels track the content branch's freshest data.
• Or: change translate-docs.yml's target to sync page-title labels back into main more eagerly, so main's frozen copies don't drift.
• Or: accept the current trade-off (curated fixes always win) as intentional and document it, if the staleness window is acceptable in practice.

Not blocking

Filed as a tracking issue rather than fixed inline in PR #189, since PR #189 already went through 10 rounds of independent readiness review focused on the restore/merge mechanics; this is a deeper data-ownership question deserving its own design discussion, not more churn on an already-large PR.

Start with .github/workflows/deploy-production.yml around line 151 and compare the HEAD and content-branch i18n/*/code.json inputs. Read translate-docs.yml to understand how generated labels reach the content branch. Done means an agreed ownership and merge policy that preserves curated fixes while avoiding stale generated labels, or documents the accepted trade-off.