brand(#18): add the ByteFolk organization avatar

[PeterGuy326]

Tracking record

Fixes #18

Consumed revision: R1 — Minimal horned B, approved by the organization owner in issue #18.

Summary

Make the selected minimal one-color horned B the canonical ByteFolk organization symbol and prepare the exact GitHub upload artifact.

• Add primary, reversed, and horizontal-lockup SVG assets.
• Add an opaque 1024×1024 RGB PNG with white background and circular-crop padding for GitHub Organization Settings.
• Add documented color, clear-space, minimum-size, reproduction, and misuse rules.
• Add a deterministic ImageMagick export/check script.
• Add a Ruby validator for SVG safety/structure, shared symbol geometry, PNG dimensions/opacity/palette, rectangular padding, and a true centered circular safe area.
• Run the brand validator in the existing required Governance workflow.

The centralized GitHub organization avatar is applied only after this PR is independently approved, merged, and green on push/main. Member avatars, repository settings, handles, pins, profile copy, permissions, and all other organization fields are out of scope.

Acceptance criteria

Acceptance criterion	Status	Implementation / evidence
AC-001 — Primary, reversed, lockup, and opaque 1024×1024 avatar share the approved symbol geometry	PASS	Identical path/rect geometry and translate(8 8) scale(.9) group transforms are validator-gated; V1/V2
AC-002 — SVGs parse, have responsive roots, avoid prohibited/external constructs, and remain recognizable at compact sizes	PASS	scripts/validate-brand-assets.rb; browser inspection at 16/32/64/512 px; V1
AC-003 — PNG is opaque 8-bit RGB, 1024×1024, white-backed, one-color, and padded for circular presentation	PASS	At center (511.5,511.5), visible ink outside the 496 px safe radius is 0; max ink radius is 488.0 px; independent mask replay has AE 0; V1–V3
AC-004 — Usage rules document colors, clear space, minimum sizes, export, and prohibited modifications	PASS	brand/bytefolk/README.md; V4
AC-005 — Governance, brand validation, deterministic export, circular-mask replay, and whitespace checks pass on the exact head	PASS	V1–V6; exact-head Governance run 33479560390 succeeded
AC-006 — Exact tracked PNG is uploaded by an organization owner after merge and green push/main CI	POST-MERGE — NOT VERIFIED	V7
AC-007 — API/anonymous readback proves the new avatar and unchanged protected organization fields	POST-MERGE — NOT VERIFIED	V7

Validation ledger

Environment: macOS 15.5 (24F74), Ruby 2.6.10, Git 2.39.5, ImageMagick 7.1.2-22, GitHub CLI 2.89.0. Base b6b9c8be284c250886953cf092174dd0cb96b402; head 3c82dccf965dbcfa57ab23b384899632202445c9.

ID	Command or check	Expected	Actual	Status
V1	ruby scripts/validate-brand-assets.rb	Three safe SVGs, shared symbol geometry, and a valid avatar pass with no ink beyond the centered 496 px safe radius	outside-circle ink=0; max ink radius 488.0px	PASS
V2	brand/bytefolk/render-avatar.sh --check	Tracked PNG is byte-identical to a fresh export	ByteFolk avatar matches symbol.svg	PASS
V3	Reproduce the centered 496 px ImageMagick mask below; inspect 16/32/64/512 renders	Masked image is pixel-identical; horned-B remains recognizable	AE=0 (0); horn tips remain complete at all four sizes	PASS
V4	ruby scripts/validate-governance.rb	Existing governance and Markdown validation remain green	Validated 5 issue forms, issue template config, 7 required files, and local Markdown links.	PASS
V5	git diff --check origin/main...HEAD	No whitespace errors	Exit 0, no output	PASS
V6	Sensitive-pattern scan plus commit metadata audit	No credential, local-path, internal-email, or private-key material; commits use public noreply metadata	Zero sensitive-pattern matches; all branch commits use noreply author and committer metadata	PASS
V7	GitHub Organization Settings upload plus API, anonymous page, and downloaded-avatar comparison	Exact tracked avatar is served; protected fields match before-state	Post-merge external mutation	NOT VERIFIED

Circular-crop replay

review_dir="$(mktemp -d)"
trap 'rm -rf -- "$review_dir"' EXIT
magick -size 1024x1024 xc:black -fill white \
  -draw 'circle 511.5,511.5 511.5,15.5' "$review_dir/safe-mask.png"
magick brand/bytefolk/avatar-1024.png "$review_dir/safe-mask.png" \
  -alpha off -compose CopyOpacity -composite -background white -alpha remove -alpha off \
  "PNG24:$review_dir/safe-crop.png"
magick compare -metric AE brand/bytefolk/avatar-1024.png "$review_dir/safe-crop.png" null:
for size in 16 32 64 512; do
  magick -background white brand/bytefolk/symbol.svg -resize "${size}x${size}!" \
    -alpha remove -alpha off "PNG24:$review_dir/icon-${size}.png"
done

compare prints 0 (0). The circle has center (511.5,511.5) and radius 496 because its edge point is (511.5,15.5).

The tracked upload artifact is brand/bytefolk/avatar-1024.png, SHA-256 08a2ebb326503dee75344ddd95b3007d0266ead1564fc9194ad8c6d8f0232dd9.

Post-merge acceptance procedure

1. Verify exact-head independent approval and required PR checks.
2. Squash merge, wait for the push/main Governance run, and confirm the merge SHA is contained in main.
3. Record authenticated organization before-state JSON and the existing avatar_url.
4. In https://github.com/organizations/bytefolk/settings/profile, upload the exact tracked brand/bytefolk/avatar-1024.png without additional editing.
5. Read back GET /orgs/bytefolk, download the new avatar_url, and compare the served image structurally with the tracked source while accounting for GitHub resizing.
6. Verify organization login, name, description, location, blog, email, social fields, pins, repository metadata, permissions, and member avatars were not changed.
7. Hard-refresh the anonymous organization page in light and dark themes and record the merge SHA, CI run URL, actor, UTC time, before/after avatar URLs, and acceptance result on issue brand: use the selected Open Herd icon-only organization avatar #18.

Tests and coverage

• Tests added: scripts/validate-brand-assets.rb, wired into the existing Governance workflow.
• Observable behavior covered: safe SVG structure, identical primary/reversed/lockup symbol geometry, reproducible raster export, exact dimensions, opaque RGB encoding, grayscale-only pixels, #141414 primary ink, at least 100 px rectangular padding, and zero visible ink beyond the centered 496 px circular safe radius.
• Coverage metric: N/A for repository governance scripts.
• Intentionally pending: live organization avatar upload and served-image readback require the merged canonical asset and owner-only GitHub UI.

Change classification

• User-visible behavior
• Internal refactor or maintenance
• Documentation only
• Build, CI, dependency, or repository configuration
• Breaking change
• Security-sensitive change

Risk and rollback

• Risk: low functional risk, medium public-presentation risk.
• Compatibility: no handle, repository, URL, package, permission, visibility, topic, pin, description, profile-copy, or member-avatar changes.
• Rollback: restore the recorded previous organization image only if the current live avatar still matches this rollout. Revert repository assets through a normal reviewed PR; do not overwrite a concurrent owner change.

Breaking or security notes

None. SVG validation rejects embedded raster data, scripts, external URLs, filters, foreign objects, and gradients. The diff contains no credential, personal data, private URL, or external dependency addition.

Author checklist

• Issue brand: use the selected Open Herd icon-only organization avatar #18 is status:ready and the organization owner approved the selected C direction.
• The branch was created from the latest protected main and contains no unrelated changes.
• Applicable local validation, export checks, visual scale checks, and security checks pass.
• The exact public upload artifact is tracked and reproducible.
• Documentation and the existing CI workflow are updated.
• The complete diff and commit metadata were reviewed for secrets, personal data, generated noise, and dependency risk.
• The PR is ready for independent review; the author does not claim reviewer approval.
• Post-merge external mutation and E4 readback remain explicitly unclaimed.

Automated assistance: Codex assisted with SVG implementation, deterministic export, validation, and evidence assembly. The organization owner remains accountable for the selected brand mark and live settings change.

Reviewer notes

Current gate: exact-head CI is green at 3c82dccf965dbcfa57ab23b384899632202445c9 in Governance run 33479560390; independent approval is still pending from an eligible reviewer.

Please focus on whether the mark is genuinely the approved minimal C direction, whether the 1024px upload preserves circular-crop padding and light/dark readability, whether the validator meaningfully blocks unsafe/drifting assets, and whether the post-merge mutation protects every non-avatar organization field.

[Bindy-lbb]

Independent review (Bindy-lbb) at exact head 8cef9fc2815fe49ab38a03a6b31c804c6ce04c77. Governance CI green, matches the linked run.

Direction match: symbol.svg reads as a clear capital B with two block "horns" and an extended lower-bowl — matches issue #18's approved R1 description well. symbol-reversed.svg uses the identical path geometry with fill:#ffffff instead of #141414, so light/dark legibility is symmetric by construction, not a separate judgment call.

Readability at scale: simulated a box-filter downscale to 16/32/64px (a reasonable proxy for how a raster avatar shrinks). Clearly legible at 32px and up — both horns and the bowl stay distinct. At 16px it gets muddy (horns become small blobs, the bowl's inner counter is hard to read), but that's a genuinely hard bar for most detailed marks and 16px real-device-pixel avatar rendering is rare (mentions/comments are typically ≥20px at 1x, doubled on retina). Not a blocker, just noting it.

Circular-crop padding — found a real gap, requesting this be addressed before merge.

scripts/validate-brand-assets.rb's padding check computes margins = [min_x, min_y, width-1-max_x, height-1-max_y] and requires each ≥100px. That's rectangular edge padding, not circular-crop safety — and those are different things. A circle inscribed in a square touches the midpoint of each edge but excludes a triangular wedge at each corner that's still within 100px of two edges.

I decoded avatar-1024.png directly (PNG chunks + zlib inflate + PNG filter reconstruction, independent of the validator's own code) and checked every ink pixel's distance from canvas center (512,512) against radius 512:

• Ink bounding box: x:[128,901] y:[134,895] — all four rectangular margins are 122–134px, comfortably clearing the validator's ≥100px check.
• But 1,725 ink pixels (~0.56% of the mark) fall outside the inscribed circle, concentrated at the two horn-tips' outer corners (e.g. pixel (128,134) is at distance ≈538 from center, ≈26px past the r=512 boundary).
• I rendered an actual circular-mask simulation and a 4x zoom crop of the top-left horn: the crop boundary visibly slices a small triangular notch off that corner. At full 1024px it's subtle to the eye, but it's a real, reproducible clip, not a rounding artifact — and it lands exactly on the "two horns" detail issue brand: use the selected Open Herd icon-only organization avatar #18 calls out as the distinguishing feature.

This means AC-003 ("sufficient circular-crop padding") is asserted PASS by a check that doesn't actually test circular geometry. Two independent ways to close this, either is fine by me:

1. Nudge the horn geometry a few SVG units inward (or add a small corner fillet, similar to the existing 2-unit rounding elsewhere in the path) so every ink pixel's distance from canvas center stays ≤512 with margin, or
2. Fix the validator to check true circular distance from center (e.g. Math.hypot(x - (width-1)/2.0, y - (height-1)/2.0) <= width/2.0 - safety_margin for every ink pixel) instead of/alongside the rectangular margins, so this class of corner-clipping can't silently pass again.

Everything else (SVG safety checks, PNG encoding/grayscale/ink-color checks, deterministic export script, usage docs, and the post-merge upload/readback/rollback procedure) looks solid and consistent with the rigor from the org-migration PRs. Holding off on approving until the circular-crop gap is addressed — happy to re-review the next exact head quickly since this is a small, scoped fix either way.

[PeterGuy326]

@Bindy-lbb Addressed the circular-crop blocker you found in #19 (comment) at exact head 3c82dccf965dbcfa57ab23b384899632202445c9.

• Kept the approved horned-B paths and proportions unchanged; primary and reversed symbols now use the lockup's existing centered translate(8 8) scale(.9) transform.
• Added a real pixel-distance gate for every visible grayscale pixel (channel < 250) using center (511.5,511.5) and safe radius 496px, 16px inside GitHub's r=512 crop. The rectangular padding gate remains.
• Added validator coverage that primary, reversed, and lockup symbol geometry/transforms stay identical.
• Negative proof: the previous PNG fails the new gate with 4,593 visible pixels outside r=496; the new PNG reports outside-circle ink=0, max ink radius 488.0px.
• Independent ImageMagick circular-mask replay is pixel-identical (AE=0 (0)). The exact mask commands are in the updated PR validation ledger.
• Rechecked 16/32/64/512 renders: the horned-B silhouette remains recognizable at 16px and is distinct from 32px upward; both horn tips remain intact.
• New deterministic PNG SHA-256: 08a2ebb326503dee75344ddd95b3007d0266ead1564fc9194ad8c6d8f0232dd9.
• Exact-head Governance CI: https://github.com/bytefolk/.github/actions/runs/33479560390 (success).

Reproduction:

ruby scripts/validate-brand-assets.rb
brand/bytefolk/render-avatar.sh --check
ruby scripts/validate-governance.rb
git diff --check origin/main...HEAD

No live organization setting or avatar was changed. Please re-review exact head 3c82dccf965dbcfa57ab23b384899632202445c9.

[Bindy-lbb]

Independent re-review (Bindy-lbb) at exact head 3c82dccf965dbcfa57ab23b384899632202445c9. Governance CI green, matches the linked run.

Independently re-verified the circular-crop fix rather than trusting the reported numbers: decoded avatar-1024.png myself (same from-scratch PNG/zlib decode as before, not reusing the repo's validator code) and checked every ink pixel's distance from canvas center (511.5, 511.5) against radius 512.

Result: 0 ink pixels outside the inscribed circle; max distance from center among all ink pixels is 487.99px — matches your reported ~488px almost exactly. Bounding box shrank from [128,134]-[901,895] to [166,173]-[863,857], consistent with the 0.9 center-scale applied to match the lockup's existing proportions. Visually the mark is unchanged in character (same B, same two horns, same bowl) just slightly more inset.

This closes the gap from my prior comment. No other issues found. Approving.