docs: refresh ByteFolk homepage with current products and clear entry points - #29
Conversation
Refs #28, consumed revision R1.
waterbro-8
left a comment
waterbro-8
left a comment
There was a problem hiding this comment.
Approving review from @waterbro-8 — requested by @PeterGuy326 on the ByteFolk group at 2026-09-08 11:47 (local) for a CODEOWNER sign-off from Bindy-lbb or waterbro-8.
I am neither the author nor the pusher of 498faea6b4b1ae4dcc4505a10be95d8eb74c7b8c (author = committer = PeterGuy326), so this approval is independent under require_last_push_approval.
Everything below was measured against this exact head (tree f0589ce7d0b939c89a19fc9f8296af3395488095) through the GitHub API at ~05:30 UTC today. Nothing is quoted from the PR body or from issue #28.
AC-by-AC result
AC-001 — PASS. bytefolk/roleweave is canonical (bytefolk/org-workbench now resolves to it). v0.1.1 is a real, public, non-draft, non-prerelease release published 2026-09-08T02:56:18Z, and both linked asset names exist with state uploaded: roleweave-0.1.1-arm64.dmg (122,076,603 B) and roleweave-0.1.1-x64.exe (105,464,927 B). The signing caveat is not an invention of this diff — the release's own notes say "The macOS packages are not yet signed with an Apple Developer ID or notarized, and the Windows installer is not Authenticode-signed." The stale installer claim on main ("Development preview; no tagged installer release yet.") is gone.
AC-002 — PASS, and the three sub-claims are each true. The quickstart does pin a published version (@fullstack-ai-infra/digital-employee@0.6.0), its own README states the path is credential-free, that validate checks package structure and eval "only checks the contract of the repository's offline fixtures. It does not invoke a model, Agent Host, MCP…". This PR's copy claims nothing about model quality, deployment readiness, or automatic cross-product integration. It also deliberately avoids naming the npm package — which is correct, because the published scope is still @fullstack-ai-infra/* while the org is bytefolk.
AC-003 — PASS. mem latest=v0.1.1 really ships MCP binaries (mem-mcp-{darwin,linux,windows}-{amd64,arm64} + checksums), mem's own README badges itself status-experimental, and the "released MCP adapter needs a running mem service" note matches. doc and design-system both return 404 on /releases/latest, so "source setup guides and no GitHub Releases" is accurate. All eight linked repositories resolve to visibility=public with no rename redirects. The two private repos in this org (context, digital-employee-platform) are not mentioned anywhere in either file — I grepped both.
AC-004 — PASS, verified at the renderer rather than assumed. The diff touches only profile/README.md and profile/README.zh-CN.md, so brand/ is untouched and the brand leg (which asserts geometry equality across symbol.svg / symbol-reversed.svg / lockup.svg) covers "geometry unchanged" for real. For light/dark I rendered the file through POST /markdown: <picture> and <source media="(prefers-color-scheme: dark)" srcset=…> both survive sanitization, and GitHub wraps the block in its own <themed-picture data-catalyst-inline="true">, so the dark variant is actually selected. EN/ZH agree on every release fact I counted — v0.1.1 ×4, arm64 ×1, x64 ×3, 1.1.x ×1, macOS ×2, Windows ×3, Apple Silicon ×2, identical on both sides.
AC-005 — PASS on the artifact, with one correction about what the artifact covers (next section). CI ran twice on this head: pull_request run 34184329147 and workflow_dispatch run 34184327532, both attempt 1, all three real steps (Validate issue forms and Markdown links, Validate ByteFolk brand assets, Check whitespace) success.
One correction to the stated evidence: the "30 links" pass is not what CI checks
The count is right — I independently counted 30 unique destinations across the two files (32 mentions each, 28 unique each). But it cannot have come from the Governance job:
scripts/validate-governance.rb:329isnext if destination.match?(/\A[A-Za-z][A-Za-z0-9+.-]*:/)— it skips every destination that carries a scheme. Both READMEs contain zero relative links (0 of 60 destinations), so the step named "…and Markdown links" validates 0 of these 30 links. What that step actually proves here is issue-form YAML shape, the 7REQUIRED_FILES, and relative-link containment.scripts/validate-brand-assets.rbnever opens a README (0 matches forREADME), so it cannot check the logo usage either — only the SVG assets themselves.
So the link claim rests on a manual pass that has not been published anywhere on this thread. That is the gap I closed, and it closes green: all 8 repos public and unredirected; mem:docs/RUN_LOCAL.md, doc:docs/RUN_LOCAL.md, doc:docs/CAPABILITIES.md, roleweave:docs/api-contract-v0.md all exist at main; CONTRIBUTING.md, GOVERNANCE.md, SECURITY.md, SUPPORT.md, CODE_OF_CONDUCT.md all exist; both brand/bytefolk/symbol*.svg exist; and all four README anchors resolve — roleweave#get-started, design-system#develop-and-verify, digital-employee-quickstart#try-a-case-safely, digital-employee-quickstart#cases.
Exactly 1 of the 30 does not resolve on main today: https://github.com/bytefolk/.github/blob/main/profile/README.zh-CN.md → 404, because this PR is what creates it. That is the correct mechanism for a cross-language link and needs no change — but it is the precise reason "all 30 links pass" is only true against the PR branch, not against main, and it is worth saying in the body so the next reader does not re-derive it.
Optional, if the org wants "links verified" to be a property CI holds rather than a person asserts: validate-governance.rb could gain an opt-in HTTP mode for profile/*.md. Nothing in this PR owes that.
Nits — none block, all one-line and optional
README.zh-CN.mdis internally inconsistent about which quickstart page it sends a Chinese reader to: 体验 CLI (line 17) and 运行官方示例 (line 43) go todigital-employee-quickstart/blob/main/README.zh-CN.md, but 示例库 (line 47) goes to the English page's#cases. That file has an equivalent heading## 案例列表, soREADME.zh-CN.md#案例列表keeps the reader in Chinese.- The mirror-image asymmetry: EN "Try the CLI" deep-links
#try-a-case-safelywhile ZH "体验 CLI" lands on the zh README root instead of its own## 安全实践一个案例heading. Fine either way; picking one depth in both files reads as deliberate. - The blockquote scopes the installers to "macOS Apple Silicon and Windows x64".
roleweaveREADME:34 states the negative outright — "Intel Mac and Linux installers are not included inv0.1.1." One clause would save an Intel-Mac visitor a 122 MB wrong click, which is the loudest remaining usability edge on the page. - Cosmetic and not fixable in this file: GitHub wraps any
<img>in a link to the image URL, so the symbol is clickable and navigates to the raw SVG.
What I did not verify, stated plainly
- I did not run the two ruby scripts locally — this machine has no ruby interpreter. I read their assertions and relied on the two green CI runs plus the step list. That is E2 for "the scripts pass", not E1 from me.
- I did not confirm that GitHub private vulnerability reporting is switched on per repository, which the "use the affected repository's Security tab" line depends on.
SECURITY.md:22already documents what to do when a repo does not show Report a vulnerability, so the homepage copy is consistent with policy whichever way that toggle sits. - I checked EN/ZH link sets and release facts, not translation quality. Whether the Chinese prose reads well to a native speaker is not mine to certify — and the
1.1.x/ signing / "no model call" sentences are the ones I did confirm carry the same facts in both languages. - Branch state is clean:
compare/main...498faea6b4b1=ahead 1 / behind 0,mergeable=true,maintip is stilld75dad353094. Somergeable_state=blockedhere is the missing approval and nothing else — no conflict, no staleness, no failing check.#29is the only open PR in this repository.
## Tracking record Refs #28, consumed revision [R2](#28 (comment)). 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. ```sh ruby scripts/validate-governance.rb ruby scripts/validate-brand-assets.rb git diff --check 99c967a 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. Current drift from the approved tracked PNG is already confirmed and recorded in #18; owner restoration and new readback are being handled there. 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.
## Tracking record Refs #37, R1. Follow-up to #28/#29/#30: RoleWeave v0.1.2 was published on 2026-09-12, but the merged homepage still offers the v0.1.1 installers. The owner authorized this version refresh before sharing the organization page with the company group. ## Summary Both profile READMEs (English and Simplified Chinese) now point the explicit RoleWeave download buttons and release-notes link at the published v0.1.2 assets, and the installer note states v0.1.2. The signing limitation text, Qoder CLI host requirement, and every other byte of the merged homepage are unchanged. No avatar, brand asset, copy rewrite, organization settings, permissions, CI, or other file changes. ## Acceptance criteria | Acceptance criterion | Status | Implementation / evidence | | --- | --- | --- | | #37 REQ-001 / AC-001: both languages link the real public v0.1.2 assets and notes page; no v0.1.1 download reference remains | PASS | Diff replaces all six `0.1.1` occurrences per file; `grep -c "0\.1\.1"` returns 0 on both files at head; all three v0.1.2 URLs return HTTP 200 (checked anonymously with curl) | | #37 REQ-002 / AC-002: installer note states v0.1.2 and keeps the accurate constraints | PASS | Note now reads "The current v0.1.2 installers…" / "当前 v0.1.2 安装包…"; platform scope, unsigned status, and Qoder CLI 1.1.x requirement unchanged and consistent with the v0.1.2 release notes | | #37 REQ-003 / AC-003: governance, brand, and whitespace checks pass; both documents render; languages agree | PASS locally (see ledger); required remote CI must pass on the candidate head | ## Validation ledger | Command or check | Expected | Actual | Evidence | | --- | --- | --- | --- | | `ruby scripts/validate-governance.rb` (clean checkout of head, UTF-8 locale) | exit 0 | exit 0 | "Validated 5 issue forms, issue template config, 7 required files, and local Markdown links." | | `ruby scripts/validate-brand-assets.rb` | exit 0 | exit 0 | "Validated 5 ByteFolk SVGs and one opaque 1024x1024 RGB avatar." | | `git diff --check 0aaff62…HEAD` | no whitespace errors | clean | no output | | `git diff --stat 0aaff62…HEAD` | only the two profile files | 2 files, 4 insertions(+), 4 deletions(-) | `profile/README.md`, `profile/README.zh-CN.md` | | Anonymous HTTP HEAD on the three v0.1.2 URLs | 200 each | 200 each | dmg, exe, and release tag pages | | GitHub Actions `Governance` on the PR head | pass | pending | required remote check | ## Tests and coverage - Tests added or changed: none; documentation-only change. The repository's executable checks (governance, brand, whitespace) cover it and were run locally at head. - Coverage before / after, when measured: not applicable; no runtime code. - Intentionally uncovered behavior and reason: none. ## Change classification - [ ] User-visible behavior - [ ] Internal refactor or maintenance - [x] Documentation only - [ ] Build, CI, dependency, or repository configuration - [ ] Breaking change - [ ] Security-sensitive change ## Risk and rollback - Risk level and affected components: minimal; two profile documents, four lines each. - Compatibility, migration, privacy, performance, or operational impact: none; no runtime, data, or settings change. - Rollback procedure: focused revert PR of the two profile files, or restore the v0.1.1 strings. ## Breaking or security notes None. ## Author checklist - [x] A maintainer confirmed that the linked issue or tracking record was ready before implementation began, or the automation was pre-authorized under `GOVERNANCE.md`. - [x] This branch was created from an up-to-date default branch and contains no unrelated changes. - [x] I ran the repository's applicable tests, lint, type checks, builds, coverage, and security checks. - [x] I added a regression test for a bug fix, or explained why one is impractical. - [x] I updated relevant documentation and changelog files. - [x] I reviewed the diff for secrets, personal data, generated artifacts, and dependency risk. - [x] The PR is ready for CI and review by someone other than the sole author. - [x] All reported results are reproducible. ## Reviewer notes - The change is a pure version-string refresh; verify with `git diff origin/main...HEAD` that only the two RoleWeave sections differ. - Independent check worth reproducing: `grep -rn "0\.1\.1" profile/` returns nothing at head, and the three v0.1.2 URLs resolve anonymously. - Required CI and a fresh CODEOWNER approval from a non-author reviewer are merge gates; squash merge after conversations are resolved.
2 participants
Tracking record
Closes #28. Consumed revision: R1.
Summary
Refresh the public ByteFolk homepage so visitors can find the released RoleWeave desktop app, the Digital Employee CLI, and supporting projects without reading internal engineering status. English is canonical, with a synchronized Simplified Chinese companion.
Use the existing light/dark brand mark, workflow-based entry points, a compact project directory, AI/developer navigation, and community support links. Follow GitHub's organization profile guidance. Reuse the existing R1 draft and update its verified product facts and integration navigation. No organization settings, pin order, policy, brand asset, or runtime changes.
Acceptance criteria
Validation ledger
ruby scripts/validate-governance.rbruby scripts/validate-brand-assets.rbgit diff --check/markdownAPI, GFM contextbytefolk/.github, both profile documentscurl -LTests and coverage
Change classification
Risk and rollback
Low documentation risk. No migration, permission, data, or operational changes. Revert the squash commit through a focused PR to restore the previous homepage. Only public project information and existing public assets are referenced.
Breaking or security notes
None.
Author checklist
Reviewer notes
Check user onboarding, release-versus-source distinctions, English/Chinese parity, and AI navigation. Automated preflight is not human approval. Codex assisted with research, documentation and validation; the submitter remains accountable.