fix: use the organization avatar in both homepage headers

[PeterGuy326]

Tracking record

Refs #28, consumed revision R2. Header-only follow-up to merged #29; the owner authorized correcting the avatar and merging after checks and independent approval. Do not reuse #29's approval for this new head.

Summary

The published homepage uses theme-specific black/white SVGs, which differ from the current organization avatar. Both English and Simplified Chinese profile headers now reference the public avatar returned by GET /orgs/bytefolk, preserving its original appearance and the existing 72-by-72 display size. Only two image blocks change; the rest of the merged homepage is byte-for-byte unchanged.

No organization avatar upload, settings, brand assets, product copy, dependency, runtime, CI, permissions, or other branch changes.

Acceptance criteria and validation ledger

Requirement / criterion	Expected behavior	Actual result
R2 REQ-004 / AC-004	Both headers use the current organization avatar, meaningful localized alt text, and 72x72 dimensions	PASS: live avatar URL and both exact headers verified; old SVG selectors removed
R2 inherited REQ-001–003 / AC-001–003	Preserve approved product copy and links	PASS: bytes after the first closing paragraph match base 99c967a04b152294fd2e9b927439fcbf37e59a86
R2 REQ-005 / AC-005	Image is available and GitHub renders both documents	PASS: anonymous avatar HTTP 200; GitHub GFM output retains avatar and localized alt text
R2 REQ-005 / AC-005	Repository checks pass	PASS locally: governance, brand assets, whitespace; required remote CI must pass on the candidate head

Reproduce

Environment: macOS arm64, Ruby 2.6.10, gh 2.89.0, Git, curl, public GitHub network access. gh uses its existing configured authentication; do not copy credentials into commands or output. Run from a checkout of this PR. These checks do not mutate repository files.

ruby scripts/validate-governance.rb
ruby scripts/validate-brand-assets.rb
git diff --check 99c967a04b152294fd2e9b927439fcbf37e59a86 HEAD
ruby -rjson -ropen3 <<'RUBY'
def read_command(*args, input: nil)
  out, status = Open3.capture2(*args, stdin_data: input)
  abort "Command failed: #{args.first}" unless status.success?
  out
end
avatar = JSON.parse(read_command('gh', 'api', 'orgs/bytefolk')).fetch('avatar_url')
base = '99c967a04b152294fd2e9b927439fcbf37e59a86'
{'profile/README.md' => 'ByteFolk organization avatar', 'profile/README.zh-CN.md' => 'ByteFolk 组织头像'}.each do |path, alt|
  text = File.read(path)
  expected = "<p align=\"center\">\n  <img src=\"#{avatar}\" alt=\"#{alt}\" width=\"72\" height=\"72\">\n"
  abort "Wrong avatar header: #{path}" unless text.split('</p>', 2).first == expected
  old = read_command('git', 'show', "#{base}:#{path}")
  abort "Body changed: #{path}" unless text.split('</p>', 2).last == old.split('</p>', 2).last
  html = read_command('gh', 'api', 'markdown', '--input', '-', input: JSON.generate(text: text, mode: 'gfm', context: 'bytefolk/.github'))
  abort "Avatar missing in render: #{path}" unless html.include?(avatar) && html.include?(alt)
  abort "Old SVG remains: #{path}" if html.include?('symbol.svg') || html.include?('symbol-reversed.svg')
  puts "PASS #{path}: avatar, dimensions, alt, unchanged body, GFM"
end
code = read_command('curl', '-sS', '-L', '-I', '-o', '/dev/null', '-w', '%{http_code}', '--max-time', '30', avatar).strip
abort "Avatar HTTP #{code}" unless code == '200'
puts 'PASS anonymous avatar HTTP 200'
RUBY

Expected and observed: all commands exit 0 after the fix. Before the change, the header equality check fails on the English document, reproducing the mismatch. The brand validator checks existing assets, not README image usage; the separate header, HTTP and GFM checks cover those claims. Other product links are unchanged, not revalidated by this avatar patch.

Tests and coverage

• No runtime or coverage change; this is a two-document image-reference correction. The executable checks above cover both languages and detect any non-header edit.
• No software CHANGELOG exists in this organization-profile repository; this tracking record and PR document the user-visible correction without creating a software release history.
• GitHub preview and independent preflight results will be recorded against the candidate before a review request. Required CI and fresh CODEOWNER approval are still merge gates.

Risk and rollback

Low documentation-only risk. The image is deliberately served from the same public GitHub avatar endpoint as the organization; later avatar updates and CDN caching may affect its appearance. The owner subsequently selected the Open Herd icon without its wordmark; that exact icon has now been uploaded through organization settings. R2 decision and fresh #18 readback supersede the earlier mistaken black B restoration and record the changed public derivative without claiming source/derivative pixel equality. Canonical export-asset alignment is tracked separately in #18. Meaningful alt text remains available if the image cannot load. No cropping, recoloring, or alternate theme image. Revert this focused commit through a PR to restore the prior header. No migration or cleanup is needed.

Breaking or security notes

None. Only the public organization avatar URL is newly referenced. No credentials, private repository data, or screenshots are included. Existing branch protection and required review are unchanged. Codex assisted with implementation and validation; the submitter remains accountable.

[waterbro-8]

Approving review from @waterbro-8 — requested by @PeterGuy326 on the ByteFolk group at 2026-09-08 14:32 (local) for a fresh CODEOWNER sign-off on this head, with the explicit note that #29's approval does not carry over.

I am neither the author nor the pusher of 7d81cf4c44913db0342107f2e75aa250403fa38d (author = committer = PeterGuy326, and it is the only commit on the branch), so this approval is independent under require_last_push_approval. .github/CODEOWNERS at this head is * @PeterGuy326 @Bindy-lbb @waterbro-8, so this is one of the two tickets that can satisfy the code-owner requirement.

Everything below was measured against this exact head (git-commit tree 2e7ca2cf343147a9ba4cab8e146c6acf5ad75a54, base 99c967a04b152294fd2e9b927439fcbf37e59a86 = live main tip) through the GitHub API and the Windows network stack today. I re-ran an equivalent of the published Reproduce block rather than reading it, and then made the measurements that block does not make. Since the body discloses that Codex assisted with implementation and validation, and R2 asks for "a fresh independent CODEOWNER approval": this review is human and the numbers below are mine, not carried over from the ledger.

AC-by-AC result — all PASS

R2 REQ-004 / AC-004 — PASS. GET /orgs/bytefolk right now returns avatar_url = https://avatars.githubusercontent.com/u/309981672?v=4, and that string appears verbatim exactly once in each document (org id 309981672 matches login=bytefolk). Localized alt text: ByteFolk organization avatar (EN) / ByteFolk 组织头像 (ZH) — the only two alt= values in each file. width="72" height="72" present once per file, unchanged from base. "No alternate black/white SVG is selected by theme" holds at the token level: <picture>, <source, prefers-color-scheme, symbol.svg, symbol-reversed.svg, raw.githubusercontent.com all go 1,1,1,1,1,2 → 0 in both files. "Reuse the original avatar without recropping or recoloring it" — the markup references the endpoint directly, so nothing in this diff resamples or tints it.

R2 inherited REQ-001–003 / AC-001–003 — PASS, and the preservation claim is exact, not approximate. Both files split on the first </p> into a changed header and an identical remainder: 5,562 bytes EN and 5,254 bytes ZH match base byte-for-byte. Stronger than the split test: at line level the whole diff is 1 added line and 4 removed lines per file (94→97 EN, 83→86 ZH lines) and no other line in either document differs, so "all product links unchanged" is proven rather than asserted. pulls/30/files = 2 files, +1/−4 each. The added line has no trailing whitespace, no tab, no CR.

R2 REQ-005 / AC-005 (rendering) — PASS, verified at the renderer. POST /markdown in gfm mode with context=bytefolk/.github returns for both languages <img src="https://avatars.githubusercontent.com/u/309981672?v=4" alt="…" width="72" height="72" style="max-width: 100%; height: auto; max-height: 72px;; aspect-ratio: 72 / 72; background-color: var(--bgColor-muted); border-radius: 6px" class="js-gh-image-fallback">, wrapped in GitHub's own <a target="_blank" rel="noopener noreferrer nofollow" href="…>. Zero symbol and zero raw.githubusercontent occurrences in either rendered document. The 72×72 survives sanitization (GitHub adds max-height: 72px + aspect-ratio: 72 / 72 itself).

R2 REQ-005 / AC-005 (availability) — PASS, and I ruled out a CDN artifact. The avatar serves 200, image/png, Content-Length: 19167, Cache-Control: max-age=300, etag: "b586f374764609e046d9bf48951470698bdac45c4ab66d5965db4b09305849c2". Three fetches — including one with a cache-busting query — returned the same 19,167 bytes and the same sha256 6349d8954e1c5894d3c91e26fddba98411117c98964821d9798d76a43308bb0d. Decoded: 460×460, 16-bit RGB, no PLTE, no tRNS, non-interlaced → opaque, extrema 10..255.

R2 REQ-005 / AC-005 (checks) — PASS on the artifact, with the same caveat R2 itself states. The Governance check-run on this exact head is completed/success, attempt 1 (run 34194838409, job 101960204253), and it is the only check this repository defines for the PR. The author's table records governance / brand assets / whitespace as PASS locally on macOS arm64 + Ruby 2.6.10 — that part is their E1, mine is E2 from CI, because this machine has no ruby. Consistent with R2's "a green asset validator is not evidence that external URLs or README image choices were checked": scripts/validate-brand-assets.rb has 0 matches for README (so it cannot see the homepage at all) and scripts/validate-governance.rb:329 is next if destination.match?(/\A[A-Za-z][A-Za-z0-9+.-]*:/), which skips every scheme-carrying URL — both documents contain only absolute URLs, so CI validates 0 of the links and 0 of the two image sources in these files. The avatar and header assertions above are therefore the only evidence that exists for those claims, and this comment is where they are recorded.

The one material finding — it is not in this diff, and R2 puts it out of scope

The PR's premise is true and I quantified it: the published header and the live organization avatar really do disagree. But the side that deviates is the live avatar, not the SVG.

brand/bytefolk/avatar-1024.png at this head has git blob 82e530bc6a10615e5bd08c7b24d2e6828ff3dd74 and sha256 08a2ebb326503dee75344ddd95b3007d0266ead1564fc9194ad8c6d8f0232dd9 — identical to the value recorded in #18's readback, identical at #18's own merge commit 18c398f7d05601559b764a13e3e81d70283b083d, and identical at this PR's base and head, so this change touches neither it nor anything under brand/. Measured, that tracked asset is 1024×1024, 8-bit RGB, opaque, 100.0 % achromatic (max channel spread 0), extrema 20..255, white background 74.8 %, rgb(20,20,20) mark 22.2 % — i.e. exactly the "black symbol on an opaque white square" that brand/bytefolk/README.md:3 calls the approved one-color horned B and that scripts/validate-brand-assets.rb:151 defends as "avatar must remain grayscale".

The currently served organization avatar is a different drawing: 460×460 with background rgb(20,20,20) at 71.3 % of sampled pixels, plus rgb(22,119,255) 13.6 % and rgb(114,46,209) 5.5 %, white 5.4 % — 22.9 % of samples are non-achromatic, max channel spread 240. Normalising both to a common grid and comparing the mark masks against the tracked asset resized 1024→460:

• per-channel MAE = 177.5 / 255 — versus the 0.664 / 255 recorded in #18's AC-007 readback;
• 88.4 % of pixels differ at all, max single-channel error 242;
• mask IoU 0.394 on the raw canvas, 0.434 after bounding-box normalisation.

So the live org avatar is no longer the approved asset, and #18 is still open (documentation, status:ready, priority:p0, unassigned) with REQ-003 / AC-006 / AC-007 being precisely "an organization owner uploads the exact tracked PNG through GitHub Organization Settings" plus a readback that the served pixels match it. GET /orgs/bytefolk now reports updated_at = 2026-09-07T01:22:40Z, i.e. after that readback was posted at 2026-09-01T16:55:06Z; that field also moves for unrelated org edits, so it dates nothing on its own — the pixel comparison above is the evidence, and it is the kind that does not need a timestamp to be conclusive.

Consequences, stated so nobody has to re-derive them:

1. This is not a defect in 7d81cf4 and I am not asking for changes on account of it. R2 explicitly lists "No avatar upload or redesign" among its non-goals, so a header PR cannot and should not fix it. The diff does exactly what the governing decision asked.
2. Merging it makes the org homepage inherit a mark that this repository's own brand guidance prohibits — brand/bytefolk/README.md:30-32 forbids "background frames, eyes, … extra colors" and forbids rearranging the horns-and-B geometry, and :17-18 says the full-body mascot "must not replace the symbol in organization avatars". The served image has two white dots that read as eyes and two extra colors.
3. The body's own risk note understates this: "later avatar updates and CDN caching may affect its appearance" describes a future risk; as of today the update has already happened. Worth one sentence in the body, not a code change.
4. The public record that needs correcting is #18, whose readback comment now asserts a false pixel match. That is the author's edit to make (or a new readback comment superseding it) — I have not touched it.
5. ?v=4 is not an avatar-version counter: I sampled 7 organizations (github, nodejs, microsoft, python, kubernetes, denoland, bytefolk) and every one returns ?v=4. So pinning this URL means the homepage follows the org avatar silently and with no diff signal — good for R2's intent ("reuse the current avatar"), but it also means nobody will get a PR when the avatar changes again. If the org wants the header pinned to this specific approved asset rather than to "whatever GitHub shows", the only way to express that in a header is a tracked file under brand/, which is what the base was doing.

My recommendation is sequencing, not revision: re-run #18's AC-006 upload (owner action, outside this repository) either before or immediately after merging this, and correct #18's readback. If the org instead decides the colored mark is now canonical, that is a brand-kit change with a decision attached to it, and #28/#18 are where it belongs.

Secondary observation — what the change gives up (authorized, recorded, not blocking)

The base render proves the removed markup was genuinely theme-adaptive, not decorative: GitHub's sanitizer preserved <picture> and <source media="(prefers-color-scheme: dark)" …> and wrapped the block in its own <themed-picture data-catalyst-inline="true"> (2 themed-picture markers in the base output, 0 at head). So #30 removes a working light/dark mechanism rather than a broken one — which is exactly what R2's sentence "No alternate black/white SVG is selected by theme" decides, so this is a documented trade-off and not drift. The practical detail that follows from it: the org avatar's own canvas is near-black (rgb(20,20,20)), so on a light GitHub theme the header is a dark square; GitHub's injected background-color: var(--bgColor-muted) sits behind an opaque image and will not soften that. I did not view the rendered page in a browser (see below), so this is read off the sanitizer output and the PNG's measured background, not off a screenshot.

Nit — one line, optional

Refs #28 lands on a body that is still R1 and states as a non-goal "No avatar replacement …" with REQ-004/AC-004 reading "keep the approved symbol geometry unchanged; support light/dark GitHub rendering". The PR does link R2 explicitly in its own Tracking record, so a reader coming from here is pointed at the right revision — the stale text only bites someone who opens #28 directly. Since #28 is open and unlabelled, a one-line pointer in its body ("AC-004 superseded by R2, see #issuecomment-5580081338") would close it. Author's call; I have not edited someone else's issue.

What I did not verify, stated plainly

• I did not run the two ruby scripts — no ruby interpreter on this machine. Their passage is the author's local E1 plus CI's E2 (Governance, success, attempt 1, this head). I read their assertions instead, which is how the :329 and README-absence facts above were obtained.
• I could not "inspect a GitHub preview before publication" (an R2 verification step) — no browser here. POST /markdown with context=bytefolk/.github is the closest machine-verifiable substitute and it is what I used; whether that step was performed by a human is the owner's attestation, not mine.
• The avatar fetch went through the Windows network stack, because avatars.githubusercontent.com and raw.githubusercontent.com are both unreachable from this WSL instance (TCP-filtered), while github.com, api.github.com, codeload.github.com and objects.githubusercontent.com are reachable. So "the old raw.githubusercontent.com URLs were unreachable" is a property of my shell, not a finding about the base — I did not score that either way, and the author's curl … -w '%{http_code}' step is a legitimate E1 from their environment.
• I did not determine when or by whom the organization avatar was last uploaded. GET /orgs/bytefolk exposes no avatar timestamp and there is no readable audit endpoint for it; updated_at is not specific to the avatar. What I established is the present pixel mismatch, which is sufficient for the recommendation and does not depend on the date.
• I did not judge translation quality of ByteFolk 组织头像 beyond "it is Chinese, names the organization, and differs from the English string as the rest of the file does".
• Branch state is clean: compare/main...7d81cf4c4491 = ahead 1 / behind 0, mergeable=true, main tip still 99c967a04b15…. So mergeable_state=blocked here was the missing approval and nothing else — no conflict, no staleness, no failing check. Before this review pulls/30/reviews was empty and requested_reviewers was [Bindy-lbb, waterbro-8]. #30 is the only open PR in this repository.

Verdict: approving. Every R2 criterion passes on the exact head. The finding about the live organization avatar is material to the page, is explicitly out of scope for this diff by R2's own non-goals, and belongs on #18 — where I would like it recorded before this merges, so the org page does not silently ship a mark its own brand kit rejects.

[PeterGuy326]

Merge ledger — approved header correction

• Canonical issue: docs: refresh the ByteFolk homepage around released products #28, consumed R2.
• Reviewed head: 7d81cf4c44913db0342107f2e75aa250403fa38d.
• Independent CODEOWNER approval: waterbro-8, 2026-09-08T07:54:45Z, on that exact head.
• Normal squash merge: 7aa4a5b65d43fd77b6cd61b0f587911ffcf0d1aa, 2026-09-09T01:57:29Z; no administrator bypass or protection changes.
• Required PR Governance: success.
• Exact push/main Governance: success.
• Independently rerun locally before merge: ruby scripts/validate-governance.rb, ruby scripts/validate-brand-assets.rb, git diff --check 99c967a04b152294fd2e9b927439fcbf37e59a86 HEAD; all exited 0.

The Governance command checks local Markdown links; it skips scheme-bearing URLs. The brand validator checks tracked brand assets, not homepage image usage. Neither result is presented as an external-link or live-avatar-identity check. The concrete current-avatar drift was recorded in #18 before merge. Owner upload and its new readback remain separate work there; no issue is closed by this ledger.