Repository navigation
blog: Bosgame M5 USB-C on Linux, and two weeks of the engine; posts get FAQPage JSON-LD - #33
Conversation
…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>
|
ready for review at 414ba25 |
bong-water-water-bong
left a comment
There was a problem hiding this comment.
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:
- The FAQPage JSON-LD needs a guard against duplicate or empty questions. A
## Frequently asked questionssection 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. - 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.
|
VERDICT: READY 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:
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 |
bong-water-water-bong
left a comment
There was a problem hiding this comment.
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.
|
VERDICT: READY at Checked against the plug test (owner, 2026-11-14 22:09–22:23 ADT, BIOS 1.10)
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 whyThe post says:
The owner's account of the same test (as relayed to the KNOWN-ISSUES entry) is "rear USB-A 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
left a comment
There was a problem hiding this comment.
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 pathTwo 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>
|
Answers to the three points:
Rebuilt against engine main: 74 pages, rc 0. ready for review at e420715 |
|
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. |
Two new blog posts and a small generator change (DOCS-REFRESH-1115, add-ons 1 and 2; lane cl-infra).
What
blog/2026-11-15-bosgame-m5-usb-c-linux-fix.mdtools/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 FAQblog/2026-11-15-strix-halo-linux-this-week.mdtools/site.py## Frequently asked questionssection becomes FAQPage JSON-LD, as doc pages already didWhy the weekly post is not
2026-11-15-this-week-in-the-engine.mdas briefed: that slug is already 2026-10-30's post. Both becameblog-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 withtwo 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.mdanddocs/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)
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.xmland that the deploy log's IndexNow step printedHTTP 200.🤖 Generated with Claude Code