The split-base build architecture, the NPM_CONFIG_PREFIX gotcha, the
hash-driven base cache reuse mechanism, and the cutover plan from
docker-publish.yml to docker-publish-split.yml were previously
scattered across:
- inline Dockerfile.base / Dockerfile.variant comments
- CHANGELOG Unreleased entries
- AGENTS.md mentions
- docker-publish-split.yml header comment
- my own session notes
Consolidate into .gitea/README.md as the canonical architectural doc.
Gitea (like GitHub) auto-renders this when navigating to .gitea/ in
the web UI, so anyone investigating 'why is CI shaped this way?'
finds it on the first click. Cross-referenced from AGENTS.md as the
first thing to read when touching CI.
Covers:
- The two release pipelines and why both exist
- Why split-base: cross-variant cache misses on layer-hash-divergence
- The 6 phases of the split-base pipeline with an ASCII diagram
- base-decide hash inputs and Docker Hub probe logic
- NPM_CONFIG_PREFIX variant-override pattern (the volume-shadow trap)
- Registry cache strategy (mode=max for cross-arch reuse)
- Wall-clock estimates: version-bump vs base-touching releases
- Validate workflow role
- Runner expectations: catthehacker image, disk reclaim, concurrency,
Gitea Actions @v4 artifact incompatibility
- 4-step migration plan from docker-publish.yml to .split.yml
- Cross-refs to related docs
Does not duplicate AGENTS.md content; links to it for domain facts and
release-day checklist.
