[Epic] Roll out ByteFolk branding across product surfaces

[PeterGuy326]

schemaVersion: requirement-record.v1
revision: R1
status: ready
priority: P1
productOwner: "@PeterGuy326"
technicalOwner: "child issue owners"
implementationOwner: "child issue owners"
humanReviewOwner: "@Bindy-lbb"
userOutcome: "A maintainer can identify the approved ByteFolk mark for every public product surface, reproduce each asset from a canonical source, and verify rollout without changing package identities, application identities, historical releases, user identity, or third-party identity."
requirements:
  - REQ-001
  - REQ-002
  - REQ-003
  - REQ-004
  - REQ-005
  - REQ-006
  - REQ-007
  - REQ-008
acceptanceCriteria:
  - AC-001
  - AC-002
  - AC-003
  - AC-004
  - AC-005
  - AC-006
  - AC-007
  - AC-008
parent: "https://github.com/bytefolk/.github/issues/24"
dependencies:
  - "https://github.com/bytefolk/.github/issues/18"
supersedes: []
lastDecisionAt: "2026-09-01T16:50:00Z"

Decision: DEC-GITHUB-BRAND-ROLLOUT-001 (2026-09-01T16:50:00Z)

Outcome

Roll out one reproducible ByteFolk brand system across the public product family while preserving each product's legitimate identity and keeping organization settings, repository social-preview uploads, package publication, and release mutation behind separately authorized writes.

This is the product-wide child required by post-rename handoff #24. The centralized organization avatar remains owned exclusively by #18.

Canonical source and surface policy

The canonical source kit is .github/brand/bytefolk/ on .github@18c398f7d05601559b764a13e3e81d70283b083d:

• symbol.svg and symbol-reversed.svg for compact ByteFolk ownership surfaces;
• lockup.svg for README, documentation, package, social, and release surfaces that have sufficient width;
• avatar-1024.png only for the centralized organization-avatar flow in brand: use the selected Open Herd icon-only organization avatar #18.

Policy:

• Use the primary symbol for compact ownership surfaces and fallback application icons; minimum rendered size is 16 px.
• Use the horizontal lockup for ownership headers and social/release cards at least 120 px wide.
• Existing doc and mem monograms may remain product marks only when paired with visible ByteFolk / product ownership and one canonical geometry source.
• Mascot use is N/A until a separate approved canonical asset, license, and usage decision exists.
• Employee/position avatars, package-provided avatars, Qoder/Claude assets, QR codes, badges, screenshots, and visual-test baselines are user, third-party, or evidence surfaces. They MUST NOT be replaced or described as ByteFolk brand assets.
• Runtime assets are vendored with canonical source commit and checksum provenance. README or package visuals may instead use immutable commit-pinned URLs; main hotlinks are forbidden.

Public-surface inventory and repository acceptance

Repository	Current public surfaces	Per-repository acceptance
.github	Canonical kit exists; profile/README.md has no lockup; no canonical mascot; repository social preview is unset	Add a versioned asset manifest and surface matrix; provide deterministic 1280x640 social-card outputs; render a light/dark-safe lockup in the organization profile. Keep organization-avatar execution exclusively in #18.
design-system	Showcase uses a placeholder B; no favicon; a superseded direction image remains as historical evidence	Replace the placeholder with canonical geometry in a showcase-local component; add a canonical favicon; update light/dark/accessibility snapshots. Preserve historical evidence and do not rename @fullstack-ai-infra/ui.
digital-employee	No ByteFolk mark or favicon; README/release history contains evidence assets; package-provided identity.avatar is user content	Add a lockup treatment to English and Chinese README/package documentation; prove the visual survives npm pack --dry-run; create a product social card; keep CLI output text-only and historical releases immutable.
digital-employee-quickstart	No brand visuals; README and case documentation only	Use the Digital Employee family lockup with a Quickstart subtitle in both READMEs; create a distinct social card; do not inject corporate or mascot assets into employee example packages.
doc	Independent doc mark is duplicated across favicon and inline/auth components; visible ByteFolk / doc text exists; social preview is unset	Retain the monogram only as the approved product mark; establish one geometry source for favicon/auth/inline variants; keep canonical ByteFolk ownership adjacent. Add repository social art; web OG/Twitter metadata is N/A until a public deployment URL exists.
mem	Independent m mark is duplicated across favicon and layout component; HTML description is empty; social preview is unset	Retain the monogram only as the approved product mark; eliminate geometry drift; add visible ByteFolk / mem ownership and repository social art. Web OG remains N/A until a public deployment URL exists. Package visuals must be packed or immutable; no npm publication is authorized here.
org-workbench	Gradient CSS square and owb rail text; no Electron application icon; Qoder/Claude assets are third-party	Replace placeholder product chrome with the canonical symbol plus visible Org Workbench name; add renderer favicon and reproducible 1024 PNG/ICNS desktop icon; configure and test packaged output and Info.plist. Preserve org.fullstack-ai-infra.org-workbench, third-party provenance, and position avatars.

Non-public repositories are inventoried by their owners outside this public record. Before any becomes public, it receives its own lockup, social-preview, and metadata acceptance gate without exposing private repository details here.

All seven public repositories currently have no configured repository social-preview image. A settings upload remains a separate repository-owner write with exact asset and rollback evidence.

Requirements

REQ-001 - Canonical manifest

The .github repository MUST own a versioned manifest covering canonical source geometry, color, clear space, minimum size, supported lockups, product-mark exceptions, checksum/provenance rules, and the current mascot N/A decision.

REQ-002 - Per-repository delivery records

Each public repository MUST receive a scoped child Issue or explicit Product Owner N/A decision. Every child defines exact files/settings, owner, dependency, rollback, and observable acceptance.

REQ-003 - Social and release surfaces

Each applicable public repository MUST receive a deterministic 1280x640, under-1-MB social card. Repository social-preview uploads, README/package inclusion, and future release use are verified separately; historical releases are immutable.

REQ-004 - Compact runtime surfaces

Favicons, application icons, navigation marks, authentication marks, and packaged desktop icons MUST remain recognizable at their intended sizes, work on light and dark backgrounds, and carry accessible naming plus reproducible visual evidence.

REQ-005 - Product-mark boundary

The doc and mem monograms may remain only as documented product marks with one geometry source and visible ByteFolk ownership. Other placeholders use the canonical symbol unless a separate product-mark decision exists.

REQ-006 - Package and documentation portability

Visuals referenced by npm/package documentation MUST either be present in the packed candidate or use immutable commit-pinned public URLs. Source metadata is not publication evidence, and this Issue authorizes no registry write.

REQ-007 - Identity preservation

The rollout MUST NOT alter npm scope, package names, dist-tags, publication state, MCP/schema/application/cache identities, Electron application IDs, user/employee/position avatars, third-party logos, evidence screenshots, or historical release filenames.

REQ-008 - Exact settings writes

Every organization-avatar or repository social-preview write requires exact repository, asset path and hash, before-state, responsible human owner, rollback, anonymous/API readback, and confirmation that unrelated settings did not change.

Acceptance criteria

• AC-001: The canonical manifest and surface matrix satisfy REQ-001 and pass repository governance/asset validation.
• AC-002: Every public repository row above has a linked child record or Product Owner-approved N/A.
• AC-003: Every applicable repository has a deterministic, validated social card and a separately authorized owner upload/readback; every accepted N/A names why.
• AC-004: Compact runtime surfaces have light/dark, minimum-size, accessibility, and packaged-artifact evidence where applicable.
• AC-005: README, documentation, package-candidate, and future-release visuals follow the lockup policy; historical releases remain unchanged.
• AC-006: A final identity audit proves zero unintended npm, application-ID, MCP/schema/cache, user-avatar, third-party-logo, or historical-evidence changes.
• AC-007: Each settings write records exact asset provenance, before/after state, rollback, and unrelated-field readback without exposing private data or credentials.
• AC-008: All linked implementation PRs pass applicable CI and receive independent review before Product Owner acceptance.

Execution and validation flow

1. Create one scoped child per repository from its current main; never use this Issue as a bulk-edit authorization.
2. Record canonical source commit and checksum before copying or rendering an asset.
3. Validate SVG safety, raster dimensions/palette/size, minimum-size rendering, light/dark behavior, accessibility, local links, package inclusion, and packaged-app icons as applicable.
4. Merge only after fresh CI and independent review.
5. Obtain separate owner authorization for each settings upload, then record sanitized readback and rollback evidence.
6. Post a requirement-decision:v1 Product Owner acceptance only after AC-001 through AC-008 are evidenced.

Non-goals

• Reopening or expanding the organization-avatar scope in brand: use the selected Open Herd icon-only organization avatar #18.
• npm login, scope reservation, publication, deprecation, dist-tag, token, membership, Trusted Publisher, or registry writes.
• Rewriting historical Releases, screenshots, validation baselines, or evidence.
• Replacing user, employee, position, package-provided, or third-party identity.
• Defining or using a mascot before a separate canonical asset and license decision.
• Publishing private repository inventory in this public Issue.

Revision history

• R1 (2026-09-01T16:50:00Z): created the product-wide Brand Rollout child required by [Maintenance] Complete the ByteFolk post-rename handoff #24; inventory and per-repository acceptance recorded; no settings or package write authorized.