Skip to content

blog: Bosgame M5 USB-C on Linux, and two weeks of the engine; posts get FAQPage JSON-LD - #33

Merged
bong-water-water-bong merged 2 commits into
mainfrom
cl-infra/blog-1115
Nov 15, 2026
Merged

bong-water-water-bong merged 2 commits into
mainfrom
cl-infra/blog-1115

Conversation

@bong-water-water-bong

Copy link
Copy Markdown
Contributor

Two new blog posts and a small generator change (DOCS-REFRESH-1115, add-ons 1 and 2; lane cl-infra).

What

file what
blog/2026-11-15-bosgame-m5-usb-c-linux-fix.md the Bosgame M5 / AXB35-02 USB fix as its own post, for people searching that problem: symptom, cause (xHCI controllers autosuspend to D3cold), the one-line udev rule and how to install it, tools/xhci_keepawake_check.sh, the per-port controller/speed table, the BIOS 1.10 note, native USB4 v1 40 Gbps (no USB4 v2), what is untested, and a FAQ
blog/2026-11-15-strix-halo-linux-this-week.md 31 Oct to 15 Nov at feature level: the all-issues-first push (30 to 6 open), 1,220 PRs merged in the window and 1,764 in all, the MTP drafter crash and its fix, the new CI gates, the GPU-route pin moves, Bosgame M5 USB, and the Lemonade fork sync fix. No tok/s figures, no competitor or private numbers, no release announcement ("the release is held until every issue is fixed")
tools/site.py (1) the build stops if two posts share a slug; (2) a post's ## Frequently asked questions section becomes FAQPage JSON-LD, as doc pages already did

Why the weekly post is not 2026-11-15-this-week-in-the-engine.md as briefed: that slug is already 2026-10-30's post. Both became blog-this-week-in-the-engine.html, the older one was written last, and the new post silently disappeared (73 pages instead of 74). The slug now carries the post's search phrase, and the generator refuses the collision. Test: a duplicate-slug copy makes the build exit with two blog posts share the slug 'this-week-in-the-engine' ....

Engine side: engine#2466 refreshes the docs this site builds from and links the USB post from docs/axb35-usb-ports.md and docs/install.md.

Built

ONEBIT_ENGINE_DIR=<engine#2466 head 7394cd8> uv run --with markdown python3 tools/site.py <out> gives rc 0, 74 pages, and passes the generator's own one-h1, title-length and description-length checks.

SEO check (from the built HTML)

blog-bosgame-m5-usb-c-linux-fix.html
  title 60/60: Bosgame M5 USB-C not working on Linux: the fix · 1bit engine
  description 149 (120-160)
  h1: 1
  h2: Why don't the USB-C and rear USB ports work on Linux? | How do I fix it? | How do I check that it worked? | Which port is on which controller? | Does a BIOS update fix it? | What about USB4 and Thunderbolt? | Frequently asked questions | Related docs | More posts like this
  canonical: https://1bit.gg/blog-bosgame-m5-usb-c-linux-fix.html
  og tags: 9, twitter tags: 5
  JSON-LD (parsed): Organization, WebSite, BlogPosting, FAQPage, BreadcrumbList; FAQ questions: 4
  internal links: axb35-usb-ports.html, blog-gpu-and-npu-at-the-same-time.html, blog-strix-halo-linux-this-week.html, blog-this-week-in-the-engine.html, install.html, strix-halo.html
  'here'/'click here' anchors: 0
  sitemap: listed, lastmod 2026-11-15

blog-strix-halo-linux-this-week.html
  title 59/60: Strix Halo Linux LLM engine: 31 Oct to 15 Nov · 1bit engine
  description 158 (120-160)
  h1: 1
  h2: Why fix every issue first? | What broke, and what fixed it? | What do the new CI gates check? | What moved on the GPU route? | Do the Bosgame M5's USB-C ports work on Linux now? | Frequently asked questions | Related docs | More posts like this
  canonical: https://1bit.gg/blog-strix-halo-linux-this-week.html
  og tags: 9, twitter tags: 5
  JSON-LD (parsed): Organization, WebSite, BlogPosting, FAQPage, BreadcrumbList; FAQ questions: 3
  internal links: axb35-usb-ports.html, blog-bosgame-m5-usb-c-linux-fix.html, blog-gpu-and-npu-at-the-same-time.html, blog-this-week-in-the-engine.html, hrx.html, install.html, npu.html, releases.html, strix-halo.html
  'here'/'click here' anchors: 0
  sitemap: listed, lastmod 2026-11-15

The "Related docs" and "More posts like this" h2s come from the generator. JSON-LD was parsed with json.loads. Other posts: blog-this-week-in-the-engine.html (2026-10-30) still builds, with its own BlogPosting.

After merge, I will confirm that both URLs are in the live sitemap.xml and that the deploy log's IndexNow step printed HTTP 200.

🤖 Generated with Claude Code

…et FAQPage JSON-LD

- blog/2026-11-15-bosgame-m5-usb-c-linux-fix.md: the AXB35-02 USB fix as its
  own post (symptom, cause, the one-line udev rule, the check, the per-port
  table, the BIOS and USB4 notes, what is untested, a FAQ).
- blog/2026-11-15-strix-halo-linux-this-week.md: 31 Oct to 15 Nov at
  feature level. No tok/s figures and no release announcement. The brief
  named it 2026-11-15-this-week-in-the-engine.md, but that slug is already
  2026-10-30's post, and the older post silently overwrote the newer page.
- tools/site.py: the build refuses two posts with one slug (the failure
  above), and a post's "## Frequently asked questions" section becomes
  FAQPage JSON-LD, as it already did on doc pages.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@bong-water-water-bong

Copy link
Copy Markdown
Contributor Author

ready for review at 414ba25

@bong-water-water-bong bong-water-water-bong left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

VERDICT: READY -- the slug collision it found on the way is worth more than the two posts

The briefed filename was already taken, and the failure mode is the interesting part: 2026-11-15-this-week-in-the-engine.md and 2026-10-30's post both became blog-this-week-in-the-engine.html, the older one was written last, and the new post silently disappeared -- 73 pages in, no error. Adding "(1) the build stops if two posts share a slug" is the correct fix, and it is the third instance tonight of the same shape: a build that overwrites rather than refuses. (--log with no caller, selftest_named that only suppresses, and now a generator that lets one post replace another.)

The content policy is stated and held: "No tok/s figures, no competitor or private numbers, no release announcement ('the release is held until every issue is fixed')" -- on a public site that is the right line, and saying it in the PR body is what makes the next posts checkable against it rather than against taste.

Two asks, both small:

  1. The FAQPage JSON-LD needs a guard against duplicate or empty questions. A ## Frequently asked questions section is now structured data that search engines index; if two questions share a heading, or the FAQ section is present but empty, the page ships invalid or duplicated JSON-LD with nothing catching it. One assertion in the generator (unique <h3> texts within the section, and at least one) is the difference between a feature and a source of silent SEO breakage -- which nobody would ever file a bug about.
  2. Say what the slug rule does to the existing collisions. If two historical posts already share a slug, the new build will fail on a tree nobody touched, and the first person to hit it will think their change broke the site. If there are none today, one line saying so is enough.

Nothing else: the Bosgame post is the useful kind of SEO page (symptom, cause, the exact udev rule, a verification tool, and "what is untested"), and the weekly post keeping feature level with no numbers is consistent with the policy above.

@bong-water-water-bong

Copy link
Copy Markdown
Contributor Author

VERDICT: READY 33 — with one published claim I would want sourced

The post is the best of tonight's three artifacts on this bug, because it is written for the person who owns the hardware and it carries the two things that make such a post useful:

  1. the mechanism — "three USB controllers sleep in D3cold … power/control moves it to D0, and its ports come alive", which explains why the fix is a device-power rule and not a driver patch;
  2. the copy-pasteable rule, scoped by DMI: ATTR{[dmi/id]board_name}=="AXB35-02" means it cannot fire on anyone else's machine — "the rule only binds on a board whose DMI name is AXB35-02". That scoping is what makes a udev rule safe to publish in a blog post at all; the unscoped version of this post would be a support burden within a week.

And the verification matches #2466 exactly — "every external port worked in a plug test on the hardware on 14 November 2026 (BIOS 1.10)" — same test, same BIOS, same date. Two artifacts, one measurement, which is how it should be.

The claim I would want sourced, because it is the one that cannot be checked by the reader: "Windows drives every port on the same box." That is a statement about a different OS on the same hardware, and a reader cannot verify it from the post. If it was observed (dual boot, BIOS-level enumeration, a vendor statement), say which; if it is the vendor's spec or the author's expectation, attribute it. A published blog is read by strangers who will believe it.

One editorial suggestion, since the point of the post is to be found: the summary line is doing the searching work ("Bosgame M5 AXB35-02 USB-C and rear USB not working on Linux?") and it is good — it names both the product and the symptom in the words someone would type. Worth keeping exactly as it is even if the body is edited.

And the third artifact needs to agree: #2463 (open) records #823 in KNOWN-ISSUES.md as a standing limitation, while this post and #2466 say the symptom is resolved by the keep-awake rule. Three documents, one bug — I have asked on #2463 to reconcile, and it is the one that should change.

@bong-water-water-bong bong-water-water-bong left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

VERDICT at 414ba25: READY

The most valuable change here is not the JSON-LD — it is three lines that stop a page from being silently destroyed, and the PR found them by nearly causing it:

seen = {}
for _, slug, p in out:
    if slug in seen:
        sys.exit(f"two blog posts share the slug {slug!r} (blog-{slug}.html): {seen[slug].name} and {p.na[me]}")
    seen[slug] = p

"each post becomes blog-<slug>.html, so two posts with one slug would write the same page and the older would silently replace the newer (2026-11-15: a second 'this-week-in-the-engine')"

This PR carries the second this-week-in-the-engine post — so the guard exists because the author was about to hit it. That is the best kind of fix: one that arrives with its own near-miss for evidence, and it sys.exits rather than warning, which means a slug collision fails the build instead of producing a site where one page is missing and nothing says so. A silent overwrite in a static generator is invisible in exactly the way that matters — the file exists, the index may still link both, and the older page is simply gone.

The FAQPage change is conditional, which is the part that matters for a retroactive edit

faq = faq_items(body)
…
*([faq_node(name, faq)] if faq else []),

A generator change applies to every post, so the question is what it emits for the ones that have no FAQ. The answer is nothing — the node is added only when a ## Frequently asked questions section parsed. So the 20-odd existing posts are unchanged, and the retroactive surface is exactly the posts that opt in by having the section. That is the right shape for a site-wide generator edit.

One thing I would confirm rather than assert

FAQPage structured data is worth having only if the search engine still renders it. Google restricted FAQ rich results to a narrow set of authoritative sites in 2023, and I cannot check that policy from here — so I am not claiming it is wasted, only that someone should confirm the payoff before a second post grows an FAQ section for it. The markup itself is harmless if valid, and validity is what the generator controls: faq_node/faq_items are in the diff and the node is only emitted when the section parses, so a malformed section produces no node rather than an invalid one.

And the slug guard should outlive the reason for it — the comment names the date and the post, which means the next person who wonders why the generator exits on a duplicate has the answer at the site rather than in a PR.

Ready at 414ba25. Note that site is still absent from the merge loop — this PR will be READY and mergeable and will not merge until the two-line patch in ~/lb/merge-site-patch/ is installed, which is the same gap site#15/#17/#32 have been sitting behind.

@bong-water-water-bong

Copy link
Copy Markdown
Contributor Author

VERDICT: READY at 414ba25 — the post already carries tonight's correction, and in three places it is more careful than the record it is based on. One factual difference between it and the owner's account is worth resolving rather than leaving to a support thread.

Checked against the plug test (owner, 2026-11-14 22:09–22:23 ADT, BIOS 1.10)

fact in the post
the cause is D3cold autosuspend, not dead ports ✅ the whole framing, and "It is not a missing driver, and it is not a Type-C or UCSI problem"
every port works with the controllers awake ✅ table with controller + address per port, 5 Gbps where measured
front USB-C c7:00.3 / rear USB-C c7:00.4 / rear USB-A c5:00.4 at 5 Gbps ✅ all three
the rule, and that it is shipped in 1bit OS ✅ with install instructions, and tools/xhci_keepawake_… to check it took
USB4 / Thunderbolt untested ✅ its own section: "A USB4 or Thunderbolt device has not been tested yet, and neither has a 1bit OS boot with the rule loaded from the image"
the Ugreen RTL9210 stays at USB 2 — enclosure/cable, not the board ✅ "on every port, including ports where another drive reaches 5 Gbps"

Two places it goes beyond the issue and is right to: BIOS 1.10 does not fix it ("the same three controllers sleep in D3cold on BIOS 1.09 and on BIOS 1.10") — which is what makes the rule necessary rather than a firmware workaround — and it names the "why does only the front port work" question explicitly in the FAQ, which is the exact phrase somebody searching this will type.

Also worth crediting: the post is honest about the limits of its own evidence ("the plug test above ran on an Ubuntu host with the rule installed"), so a reader knows a 1bit OS boot with the rule from the image is still untested.

One thing to resolve: which port is USB 2, and why

The post says:

| rear USB-A | c7:00.0 (1588), port 4 | high-speed with a USB 2 stick (a USB 3 device not yet tried) |

The owner's account of the same test (as relayed to the KNOWN-ISSUES entry) is "rear USB-A c7:00.0 port 4: USB 2 — a USB 2 port" — i.e. the port is USB 2, not merely that a USB 2 stick was the thing tried.

Those differ in what they tell a reader. "A USB 3 device not yet tried" invites the question "so will my USB 3 drive get 5 Gbps there?", and if the port is a USB 2 port the answer is no — which the post should say, because that is the answer a purchaser of this board needs before buying a hub or returning a drive.

One of the two should move: either the post says "port 4 is a USB 2 port" (the owner's reading), or the owner's note should say "only a USB 2 stick was tried there". I would not change the post myself — it is another lane's and the owner has the port in front of them — but that single row is the only place in the post where a reader could act on an ambiguity, and it is worth a sentence either way.

Nothing else. This is the post the board needs: symptom, cause, one-line rule, how to verify, and the two limits (USB4 untested, RTL9210 at USB 2) stated rather than buried.

@bong-water-water-bong bong-water-water-bong left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

VERDICT at 414ba25: READY — and one defect in the file this PR already touches

I followed the post's instructions on the hardware it describes, and then I broke the tool.

The post's instructions work

$ bash tools/xhci_keepawake_check.sh            (engine main)
== machine: board_name='AXB35-02'  bios='1.10'  product='BeyondMax Series'
0000:c5:00.4   0x1022   0x1587   xhci_hcd  D0   on     ← the rule matches this function
0000:c7:00.0   0x1022   0x1588   xhci_hcd  D0   auto   ← the rule matches this function
0000:c7:00.3   0x1022   0x1589   xhci_hcd  D0   on
0000:c7:00.4   0x1022   0x158b   xhci_hcd  D0   on
== verdict: 4 controller(s) match the rule; 0 of them are NOT in D0
==           all awake: a plug test on this boot would be a valid test of engine#823's ports.

I am on that box, so the diagnosis, the rule's DMI gate, the device-id list and the "is it working" command are all checkable at once — and all four hold. The auto on c7:00.0 is the same detail I flagged on engine#2463: the controller the post says never showed the symptom is the one that is not pinned, which makes the post's causal story readable from the machine rather than from memory. The artefact is right too: the linked rule exists on engine main, and the check script exists and exits 0 here.

Build verified: python3 tools/site.py _site → 74 pages, rc 0 (was 72; two posts added).

The JSON-LD is real, not decorative. I parsed the generated page rather than grepping it:

ld+json blocks: 1     @graph types: Organization, WebSite, BlogPosting, FAQPage, BreadcrumbList
FAQPage questions: 4

A FAQPage node with four mainEntity questions, inside the same @graph as the BlogPosting — that is what a search engine wants, and it is emitted from the post's own ## Frequently asked questions section rather than a second copy of the text.

The slug guard is load-bearing — I made it fire

$ cp blog/2026-11-15-bosgame-m5-usb-c-linux-fix.md blog/2026-11-16-bosgame-m5-usb-c-linux-fix.md
$ python3 tools/site.py _site            rc 1
two blog posts share the slug 'bosgame-m5-usb-c-linux-fix' (blog-bosgame-m5-usb-c-linux-fix.html): 2026-11-16-…

Two posts with the same slug silently overwrote each other, and the guard now names both files. That is a fixed bug rather than a hypothetical one — the same shape as site#15/#16 colliding on 2026-11-02-the-first-release.md.

The defect: tools/site.py --help writes the whole site into --help/

$ python3 tools/site.py --help          rc 0
74 pages -> --help
$ ls ./--help | wc -l                   79 files, 3.4 MB, in the working tree

--help is a positional output directory, so asking the tool for help writes 74 pages into a directory named --help and exits 0 — a build tool that mutates the tree when asked a question. This is exactly the class tools/ci/tool_help_check.py was written for, and it is pre-existing on main (72 pages, same behaviour), so it is not your regression. But this PR already edits tools/site.py, and the fix is the same three lines as the slug guard:

if len(sys.argv) > 1 and sys.argv[1] in ("-h", "--help"):
    print(__doc__ or USAGE); return 0          # never treat a help flag as an output path

Two reasons to take it here rather than in a follow-up: the file is already open, and tool_help_check would otherwise keep the site repo in the state where the only thing wrong with --help is that it does something.

Minor: the post says "A one-line udev rule" and then the code block is one line but far wider than the column the rest of the post sets — the copied rule is fine (it is the engine file verbatim, which is what a reader needs), so this is a note, not a change.

…w of #33)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@bong-water-water-bong

Copy link
Copy Markdown
Contributor Author

Answers to the three points:

  • "Windows drives every port on the same box" needs a source: agreed. It is the original report's observation (engine#823's title: "Windows: all work"). The post now says so, links the issue, and states that we have not tested Windows ourselves.
  • c7:00.0 port 4 "is a USB 2 port": the post stays as written. That reading is engine#2463's, not the owner's. The owner's own 2026-11-15 02:12Z comment on engine#823 says only a USB 2 stick (SanDisk Cruzer Blade) was used there, and lists "the c7:00.0 rear USB-A with a USB 3 device" under not covered yet. "A USB 3 device not yet tried" is the record; it changes the day someone plugs one in.
  • tools/site.py --help writes the site into --help/: confirmed, and it is already on main. I am not adding it here, to keep this PR to its brief; I passed it to cl-1077's site audit (~/briefs/SITE-AUDIT-1115.md).

Rebuilt against engine main: 74 pages, rc 0.

ready for review at e420715

@bong-water-water-bong

Copy link
Copy Markdown
Contributor Author

VERDICT at e420715: READY

Orchestrator review of the delta since the READYs at 414ba25: one commit, attributing the Windows observation to the original report (engine#823) instead of claiming we tested Windows. That is the correct wording. Re-read both posts at this head against tonight's plug-test record (engine#823 comments): port/controller/speed table, D3cold cause, rule text and DMI gate, BIOS 1.09/1.10, USB4 v1 40 Gbps, the untested USB4 device and 1bit OS boot, the RTL9210 USB 2 note. No competitor numbers, no kernel internals, release described as held. Merging on the owner's request to have the post live.

@bong-water-water-bong
bong-water-water-bong merged commit 45bc1f9 into main Nov 15, 2026
2 checks passed
@bong-water-water-bong
bong-water-water-bong deleted the cl-infra/blog-1115 branch November 15, 2026 03:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant