From 1aae98a6d34996be5222f864adde0ccf3d9dacb3 Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Fri, 7 Aug 2026 22:00:35 -0700 Subject: [PATCH 1/5] Restore gallery captions and items the conversion flattened (#55) * Restore gallery captions and items the conversion flattened Closes #52. A gallery is a flex row whose column widths come from `.gallery-cols-N figure`, so anything inside it that is not a figure gets no width from that rule and is laid out as one more item in the row. Three variants of that survived the conversion, and no gate could see any of them: every media check reasons about a URL, and misplaced content resolves and is linked exactly as correct content is. Each was verified against the captured live site before being changed rather than inferred from the markup, and the first is why that matters. Eleven captions in the FLAIR post were written as text trailing the last figure shortcode. Reading only the source, the obvious fix is to move the text into that figure's caption parameter, which is what the review suggested. The capture shows all eleven were blocks-gallery-caption elements, captions for the set, so that fix would have attributed a caption describing four images to whichever one sorted last and would have looked right. They move to a caption on the gallery instead. The other two were gallery items the conversion emitted as plain markdown, two bare images and eight linked ones, against li.blocks-gallery-item > figure in the original. Both become figure shortcodes, the linked ones through the parameter the theme already has, which puts the anchor back inside the figure where it was. The container becomes a figure, because figcaption is only valid as a figure's child. The reset already sets figure { margin: 0 } and the theme already styles figure > figcaption, so a set caption needed one rule: a full-width flex basis, without which it packs onto the end of the last row and reads as a caption for whichever image it lands beside. check-url-parity.py gains the gate that would have caught all of this, parsing the built pages rather than matching text, since nested figures defeat a regex. Demonstrated failing before being trusted: against the pre-fix content it reports 27 stray nodes and exits 1, and it distinguishes the shapes rather than counting them, naming bare text and each stray element type. The gate found more than the review did. The linked-image variant is on a post neither the review nor the issue mentioned, and it was found only by running the check across all 19 pages that carry a gallery. Verified through make-release.sh and against the local mirror: PASS - 1245 URLs honored, with assets at 1049 and orphans at 98, both unmoved, so no media was lost or newly orphaned by the rewrite. Co-Authored-By: Claude Opus 5 (1M context) * Reject a gallery page by the class token, not by one spelling of it Both from review on #55. The cheap reject read `class="gallery`, which assumes the quotes survive and that the token sorts first. Minification drops the quotes around a value that does not need one and says nothing about class order, so `class=gallery` and `class="foo gallery"` both skipped the parser entirely and the gate passed vacuously on a page whose markup was merely spelled differently. It matches the bare word now, which cannot skip a page the parser would find, since the parser requires the class token and a page carrying it always contains the string. Matching a page that only mentions the word costs one parse. The printed count is now taken from what the parser found rather than from the reject, so the broader test does not turn "pages carrying a gallery" into "pages the word appears on". The shortcode comment claimed a set caption needed no rule of its own, while this branch adds one. It does need it, and for a reason worth keeping: the gallery is a flex container, so without a full-width basis the caption packs onto the end of the last row and reads as a caption for whichever image it lands beside. The comment now says so and says not to remove the rule as redundant. Verified on all three spellings, quoted, unquoted, and reordered, each carrying a known stray node: all three are now detected, and the first two were not before. The site itself is unchanged at 19 pages with galleries and 0 stray nodes. Co-Authored-By: Claude Opus 5 (1M context) * Name the invariant the gallery check tests, not the shapes it has met From a suppressed finding on #55, which was right: the docstring said "both conversion artifacts" while the README and the description say three. It was written after two were known and never revised when the check itself found the third. Rewritten to say what it actually tests. Three source patterns reached it and they arrive as three different HTML shapes, so an enumeration is a list to extend every time the conversion surprises us again. The invariant is that a gallery holds figures and its own caption, and that is what covers the shape nobody has thought of yet, which is how the third was found after the first two. Co-Authored-By: Claude Opus 5 (1M context) * Record why the gallery scanner has no handle_startendtag From a suppressed finding on #55, which reasoned correctly from the code and reached the wrong conclusion about the base class. HTMLParser forwards a self-closing tag to handle_starttag and then handle_endtag, so `
`, `
` and `` are already reported as stray children and already leave the depth balanced. Verified on those three spellings and on a self-closing non-void `
`, which enters and exits correctly and lets the `

` after it be seen. Adding the override the finding asks for is what would break this, by counting a pair the base class already splits. That is worth a comment rather than a reply nobody reading the file later will find. Co-Authored-By: Claude Opus 5 (1M context) * Say what a gallery failure found, rather than calling it missing From a suppressed finding on #55. The shared summary printed `FAIL gallery: N missing` for a check whose findings are nodes that are present, which is the entire complaint about them. Each label can now name its own noun, defaulting to "missing" so the four older checks are unchanged and a check added later reads the way they do unless it says otherwise. Verified by forcing a failure: `FAIL gallery: 15 stray nodes`. Co-Authored-By: Claude Opus 5 (1M context) --------- Co-authored-by: Claude Opus 5 (1M context) --- assets/css/extended/custom.css | 10 ++ checks/README.md | 18 +++ checks/check-url-parity.py | 120 ++++++++++++++++-- ...-a-supermicro-bpn-sas3-846el1-backplane.md | 4 +- .../06/21/moving-from-unraid-to-proxmox-ve.md | 16 +-- ...ents-to-keep-room-temperatures-balanced.md | 44 +++---- layouts/shortcodes/gallery.html | 19 ++- 7 files changed, 189 insertions(+), 42 deletions(-) diff --git a/assets/css/extended/custom.css b/assets/css/extended/custom.css index 4fe3fe5..c7c0eff 100644 --- a/assets/css/extended/custom.css +++ b/assets/css/extended/custom.css @@ -38,6 +38,16 @@ body { margin: 1rem auto; } +/* + The set caption is a flex item like the figures beside it, so without a full-width basis it + packs onto the end of the last row and reads as a caption for whichever image it lands next + to. Full width puts it on its own row under the set, which is what it describes. +*/ +.gallery > figcaption { + flex: 0 0 100%; + text-align: center; +} + .gallery-cols-1 figure { width: 100%; } diff --git a/checks/README.md b/checks/README.md index 435916f..83bc682 100644 --- a/checks/README.md +++ b/checks/README.md @@ -84,6 +84,24 @@ A count is all the check can observe, and two causes reach each direction: it ri **Both directions read absolute references as well as relative ones.** Hugo writes an absolute URL wherever a template resolves one against the base, which the entry-cover image on every list page does. Reading only rooted paths made those files look linked from nowhere while they were being displayed, and left a broken one unchecked in the other direction. The origin is read from the home page's canonical link rather than assumed, since staging and production build with different base URLs and a hardcoded host would check one environment's output against another's. No canonical link is a hard failure, because a guessed origin inflates the orphan count by exactly the pages that use one. +## The gallery check, which no direction above can reach + +Every check above reasons about a URL: whether it renders, whether it resolves, whether anything points at it. Content misplaced **inside** a gallery satisfies all of that. The file exists, the reference resolves, and something links it, so the media surface is green in both directions while the page is laid out wrong. The defect is one of structure, which is why three variants of it survived the conversion and every gate since. + +A gallery is a flex row whose column widths come from `.gallery-cols-N figure`. Anything in there that is not a `figure` gets no width from that rule and is rendered as one more item in the row. So the check reads the built pages and fails on any direct child of a gallery container that is not a `figure` or the gallery's own `figcaption`. + +The three shapes it found, all of them conversion artifacts, and each verified against the captured live site before being changed: + +| Shape in the markdown | What the old platform had | +| --- | --- | +| Caption text appended after the last `figure` shortcode's `}}` | `

`, a caption for the **set** | +| A bare `![](…)` image | `
  • ` | +| A linked `[![](…)](…)` image | the same, with an `` **inside** the figure | + +**The first shape is why the capture is consulted rather than the markup.** A reviewer reading only the source reasonably suggests moving the text into the last figure's `caption` parameter, which is what a per-image caption would need. The capture shows all eleven were gallery-level captions, so that fix would have attributed a caption for a set of four images to whichever one happened to be last, and it would have looked correct. + +The gallery shortcode therefore takes a `caption` of its own and renders the container as a `figure`, since `figcaption` is only valid as a figure's child. The theme already styles `figure > figcaption`, so a set caption needs no rule beyond a full-width flex basis to keep it off the end of the last row. + ## What the orphans are The count is not a backlog. It opened at 120 and was adjudicated against the captured live site under `blog-capture/mirror/`, which holds a crawl of the old platform including all 328 URLs the contract requires: diff --git a/checks/check-url-parity.py b/checks/check-url-parity.py index c2d4493..2d017fa 100755 --- a/checks/check-url-parity.py +++ b/checks/check-url-parity.py @@ -10,6 +10,7 @@ import pathlib import re import sys +from html.parser import HTMLParser from urllib.parse import unquote # A truncated list would make every assertion below it pass vacuously while the gate stays green. @@ -37,6 +38,12 @@ # slack can never accumulate for a later regression to hide in. ORPHANED_MEDIA = 98 +# Every check above returns a list, and the shared summary called all of them "missing". That is +# what a URL that did not build is, and it is not what a stray node inside a gallery is: those are +# present, which is the whole complaint. The default stays "missing" so a check added later reads +# the way the older ones do unless it says otherwise. +FAILURE_NOUN = {"gallery": "stray nodes"} + def load(name): lines = [ln.strip() for ln in (CHECKS / name).read_text().splitlines()] @@ -189,6 +196,102 @@ def check_orphans(public, refs): return orphaned +class GalleryScan(HTMLParser): + """Collect anything inside a gallery container that is not one of its permitted children. + + A gallery is a flex row of figures, so its column widths are set by `.gallery-cols-N figure`. + Anything else landing in there is not laid out by that rule and is rendered as one more item + in the row. + + This reads the built HTML, so it sees fewer shapes than the markdown has, and deliberately: + three source patterns reached it, a set caption written as text trailing a figure shortcode, + a bare markdown image, and a linked one, and they arrive here as a bare text node, a `

    ` + wrapping images, and an `` with a `
    ` beside it. Enumerating source patterns would + make this a list to extend every time the conversion surprises us again. Naming the one + invariant instead, that a gallery holds figures and its own caption, covers the shape nobody + has thought of yet, which is how the third of the three was found after the first two. + """ + + # A void element never closes, so counting it as an open tag desynchronizes the depth for the + # rest of the document and every later gallery reads as containing whatever follows it. + VOID = {"area", "base", "br", "col", "embed", "hr", "img", "input", + "link", "meta", "param", "source", "track", "wbr"} + ALLOWED = {"figure", "figcaption"} + + # There is deliberately no handle_startendtag override. HTMLParser's own implementation + # forwards a self-closing tag to handle_starttag and then handle_endtag, so `
    `, `
    ` + # and `` are already reported and already leave the depth balanced. Adding an override + # to "support" them is what would break it, by counting a pair the base class already splits. + # Verified on those three spellings and on a self-closing non-void `

    `. + + def __init__(self): + super().__init__(convert_charrefs=True) + self.findings = [] + self.saw_gallery = False + # None outside a gallery; otherwise the number of elements open within the current one, + # so zero means the parser is looking at a direct child. + self.depth = None + + def handle_starttag(self, tag, attrs): + classes = dict(attrs).get("class", "").split() + if self.depth is None: + if tag == "figure" and "gallery" in classes: + self.depth = 0 + self.saw_gallery = True + return + if self.depth == 0 and tag not in self.ALLOWED: + self.findings.append(f"<{tag}> as a direct child") + if tag not in self.VOID: + self.depth += 1 + + def handle_endtag(self, tag): + if self.depth is None or tag in self.VOID: + return + if self.depth == 0: + # The gallery's own closing tag. + self.depth = None + else: + self.depth -= 1 + + def handle_data(self, data): + # Whitespace between elements is just the template's formatting. + if self.depth == 0 and data.strip(): + self.findings.append(f"bare text {data.strip()[:60]!r}") + + +def check_galleries(public): + """Check that every gallery holds only figures and its own caption. + + Neither the assets nor the orphans check can see this: both ask whether a reference resolves + or is reached, and content misplaced inside a gallery resolves and is reached exactly as it + would anywhere else. The defect is purely one of structure, so nothing that reasons about + URLs can observe it, which is why it survived the conversion and every gate since. + """ + findings, pages = [], 0 + for path in sorted(public.rglob("index.html")): + html = path.read_text(encoding="utf-8", errors="replace") + # Cheap reject first, since parsing every built page costs far more than one substring + # test and galleries appear on a handful of them. The test is the bare word rather than + # `class="gallery`, because minification drops the quotes around a value that does not + # need them and says nothing about class order, so the quoted form skips a page whose + # markup is merely spelled differently and the gate passes vacuously. This form cannot: + # the parser below requires the class token `gallery`, so a page it would find always + # contains this string. Matching a page that only mentions the word costs one parse. + if "gallery" not in html: + continue + scan = GalleryScan() + scan.feed(html) + # Counted from what the parser actually found rather than from the reject above, so the + # reported number stays "pages carrying a gallery" and not "pages the word appears on". + if not scan.saw_gallery: + continue + pages += 1 + rel = str(path.relative_to(public)).replace("\\", "/") + findings += [f"{rel}: {finding}" for finding in scan.findings] + print(f"gallery: {pages} pages with galleries, {len(findings)} stray nodes inside one") + return findings + + def main(argv): if len(argv) != 2: sys.exit(f"usage: {argv[0]} ") @@ -198,26 +301,27 @@ def main(argv): refs = collect_refs(public) failures = [] - for label, missing in ( + for label, found in ( ("render", check_render(public)), ("media", check_media(public)), ("assets", check_assets(public, refs)), ("orphans", check_orphans(public, refs)), + ("gallery", check_galleries(public)), ): - if missing: - failures.append((label, missing)) + if found: + failures.append((label, found)) if not failures: print("\nPASS - the built site honors the URL contract") return 0 print() - for label, missing in failures: - print(f"FAIL {label}: {len(missing)} missing") - for item in missing[:20]: + for label, found in failures: + print(f"FAIL {label}: {len(found)} {FAILURE_NOUN.get(label, 'missing')}") + for item in found[:20]: print(f" {item}") - if len(missing) > 20: - print(f" ... and {len(missing) - 20} more") + if len(found) > 20: + print(f" ... and {len(found) - 20} more") return 1 diff --git a/content/posts/2020/02/02/recovering-the-firmware-on-a-supermicro-bpn-sas3-846el1-backplane.md b/content/posts/2020/02/02/recovering-the-firmware-on-a-supermicro-bpn-sas3-846el1-backplane.md index 625954c..d333873 100644 --- a/content/posts/2020/02/02/recovering-the-firmware-on-a-supermicro-bpn-sas3-846el1-backplane.md +++ b/content/posts/2020/02/02/recovering-the-firmware-on-a-supermicro-bpn-sas3-846el1-backplane.md @@ -37,8 +37,8 @@ I removed the motherboard from the old chassis and installed it in the new SC846 {{< figure src="/media/2020/01/img%5F5897.jpg?w=1024" alt="" caption="" >}} {{< figure src="/media/2020/01/img%5F5898.jpg?w=1024" alt="" caption="" >}} {{< figure src="/media/2020/01/img%5F5899.jpg?w=768" alt="" caption="" >}} -![](/media/2020/02/img_5973.jpg?w=1024) -![](/media/2020/02/img_5980.jpg?w=768) +{{< figure src="/media/2020/02/img_5973.jpg?w=1024" alt="" caption="" >}} +{{< figure src="/media/2020/02/img_5980.jpg?w=768" alt="" caption="" >}} {{< /gallery >}} I powered the machine up through remote IPMI KVM, all looked good, and I booted into my Ubuntu Server USB stick so I could SSH into the box, and update the firmware. diff --git a/content/posts/2020/06/21/moving-from-unraid-to-proxmox-ve.md b/content/posts/2020/06/21/moving-from-unraid-to-proxmox-ve.md index 1c9ee23..dae8410 100644 --- a/content/posts/2020/06/21/moving-from-unraid-to-proxmox-ve.md +++ b/content/posts/2020/06/21/moving-from-unraid-to-proxmox-ve.md @@ -610,12 +610,12 @@ Here are a few screenshot of the end result: {{< gallery cols="3" >}} -[![](/media/2020/06/2020-06-21-1.png?w=1024)](/media/2020/06/2020-06-21-1.png?w=1024) -[![](/media/2020/06/2020-06-21-2.png?w=1024)](/media/2020/06/2020-06-21-2.png?w=1024) -[![](/media/2020/06/2020-06-21-3.png?w=1024)](/media/2020/06/2020-06-21-3.png?w=1024) -[![](/media/2020/06/2020-06-21-4.png?w=1024)](/media/2020/06/2020-06-21-4.png?w=1024) -[![](/media/2020/06/2020-06-21-9.png?w=1024)](/media/2020/06/2020-06-21-9.png?w=1024) -[![](/media/2020/06/2020-06-21-6.png?w=1024)](/media/2020/06/2020-06-21-6.png?w=1024) -[![](/media/2020/06/2020-06-21-7.png?w=1024)](/media/2020/06/2020-06-21-7.png?w=1024) -[![](/media/2020/06/2020-06-21-8.png?w=1024)](/media/2020/06/2020-06-21-8.png?w=1024) +{{< figure src="/media/2020/06/2020-06-21-1.png?w=1024" alt="" link="/media/2020/06/2020-06-21-1.png?w=1024" caption="" >}} +{{< figure src="/media/2020/06/2020-06-21-2.png?w=1024" alt="" link="/media/2020/06/2020-06-21-2.png?w=1024" caption="" >}} +{{< figure src="/media/2020/06/2020-06-21-3.png?w=1024" alt="" link="/media/2020/06/2020-06-21-3.png?w=1024" caption="" >}} +{{< figure src="/media/2020/06/2020-06-21-4.png?w=1024" alt="" link="/media/2020/06/2020-06-21-4.png?w=1024" caption="" >}} +{{< figure src="/media/2020/06/2020-06-21-9.png?w=1024" alt="" link="/media/2020/06/2020-06-21-9.png?w=1024" caption="" >}} +{{< figure src="/media/2020/06/2020-06-21-6.png?w=1024" alt="" link="/media/2020/06/2020-06-21-6.png?w=1024" caption="" >}} +{{< figure src="/media/2020/06/2020-06-21-7.png?w=1024" alt="" link="/media/2020/06/2020-06-21-7.png?w=1024" caption="" >}} +{{< figure src="/media/2020/06/2020-06-21-8.png?w=1024" alt="" link="/media/2020/06/2020-06-21-8.png?w=1024" caption="" >}} {{< /gallery >}} diff --git a/content/posts/2022/10/30/installing-flair-smart-vents-to-keep-room-temperatures-balanced.md b/content/posts/2022/10/30/installing-flair-smart-vents-to-keep-room-temperatures-balanced.md index 93d29bd..af3b68d 100644 --- a/content/posts/2022/10/30/installing-flair-smart-vents-to-keep-room-temperatures-balanced.md +++ b/content/posts/2022/10/30/installing-flair-smart-vents-to-keep-room-temperatures-balanced.md @@ -56,14 +56,14 @@ To get started, I ordered a [puck](https://flair.co/products/puck) and a couple The look and feel of the Puck was a bit disappointing for the price, small non-touch monochrome display, and uneven feeling push to actuate action. The [Flair Puck](https://amzn.to/3rOr6gS) is about $119 while an [Ecobee3 Lite](https://amzn.to/3TfSNLo) is about $149, and the Ecobee has a nice big color touch screen. Granted, the puck is about half the size of the Ecobee so more discreet, and I'm not planning on using the puck for anything other than an internet gateway, so look and feel was not that important to me. -{{< gallery cols="4" >}} +{{< gallery cols="4" caption="FLAIR puck vs. my old Ecobee3" >}} {{< figure src="/media/2022/10/img_1646.jpg?w=1024" alt="" caption="" >}} {{< figure src="/media/2022/10/img_1647.jpg?w=594" alt="" caption="" >}} {{< figure src="/media/2022/10/img_1655.jpg?w=665" alt="" caption="" >}} -{{< figure src="/media/2022/10/img_1657.jpg?w=426" alt="" caption="" >}}FLAIR puck vs. my old Ecobee3 +{{< figure src="/media/2022/10/img_1657.jpg?w=426" alt="" caption="" >}} {{< /gallery >}} I installed the iOS app, set the puck in gateway only mode, followed the installation steps in the app, including creating an account, connecting the puck to WiFi, and connecting Flair to Ecobee for access to my thermostats. I installed batteries in a vent, without installing the actual vent but observing its behavior, and added the vent to Flair using the iOS app by entering pairing mode, no problems. @@ -71,10 +71,10 @@ I installed the iOS app, set the puck in gateway only mode, followed the install When I completed the required setup steps I logged into the web portal on my PC to explore, and I was confused to see that the system appeared to be in heating mode. I verified that Ecobee was still in cooling mode, and I changed the Flair mode from Heat to Manual. -{{< gallery cols="1" >}} +{{< gallery cols="1" caption="Ecobee in cool mode while FLAIR reports heat mode" >}} {{< figure src="/media/2022/10/2022-10-06-1.png?w=1024" alt="" caption="" >}} -{{< figure src="/media/2022/10/2022-10-06.png?w=1024" alt="" caption="" >}}Ecobee in cool mode while FLAIR reports heat mode +{{< figure src="/media/2022/10/2022-10-06.png?w=1024" alt="" caption="" >}} {{< /gallery >}} I created a post in the Flair [community forum](https://support.flair.co/hc/en-us/community/topics/115000084371-Flair-Discussion) asking for help, next day a support ticket was logged for me by a moderator, and it took another four days for support to respond. A five day turnaround for support is not very responsive. @@ -92,33 +92,33 @@ The Flair vents are longer but narrower than my current vents, and that was a bi I ended up removing the old vents, and visited my paint store several times to color match various wall or ceiling colors, I sanded, caulked, and patched drywall spaces around ducts. It took several weekends of my time, I am not a great at drywalling or painting, the result is not very pretty, but the vents are up. -{{< gallery cols="1" >}} +{{< gallery cols="1" caption="FLAIR vent construction" >}} {{< figure src="/media/2022/10/img%5F1642.jpg?w=604" alt="" caption="" >}} {{< figure src="/media/2022/10/img%5F1643.jpg?w=603" alt="" caption="" >}} -{{< figure src="/media/2022/10/img%5F1644.jpg?w=943" alt="" caption="" >}}FLAIR vent construction +{{< figure src="/media/2022/10/img%5F1644.jpg?w=943" alt="" caption="" >}} {{< /gallery >}} -{{< gallery cols="5" >}} +{{< gallery cols="5" caption="FLAIR vent is smaller than standard vents" >}} {{< figure src="/media/2022/10/img_1651.jpg?w=663" alt="" caption="" >}} {{< figure src="/media/2022/10/img_1663-edited.jpg" alt="" caption="" >}} {{< figure src="/media/2022/10/img_1665-edited-1.jpg" alt="" caption="" >}} -{{< figure src="/media/2022/10/img_1668.jpg?w=589" alt="" caption="" >}}FLAIR vent is smaller than standard vents +{{< figure src="/media/2022/10/img_1668.jpg?w=589" alt="" caption="" >}} {{< /gallery >}} With all the trouble caused by the too narrow vents, I wondered if there was a standard to sizes, and if so, if Flair was following it. I researched vent sizes across several HVAC supply sites and hardware stores, and my conclusion is that the Flair [vents](https://www.flair.co/smart-vent-engineering-and-dimensional-data-public) are always longer and narrower than standard wall/ceiling vent sizes (I did not compare floor vent sizes). -{{< gallery cols="1" >}} +{{< gallery cols="1" caption="FLAIR vent sizes vs. standard vents sizes" >}} {{< figure src="/media/2022/10/screenshot-2022-10-13-210638.png?w=1024" alt="" caption="" >}} {{< figure src="/media/2022/10/screenshot-2022-10-13-210202.png?w=949" alt="" caption="" >}} -{{< figure src="/media/2022/10/screenshot-2022-10-13-210127.png?w=751" alt="" caption="" >}}FLAIR vent sizes vs. standard vents sizes +{{< figure src="/media/2022/10/screenshot-2022-10-13-210127.png?w=751" alt="" caption="" >}} {{< /gallery >}} In my opinion making the vents smaller than common sizes is a major design flaw, and I do wonder if Flair designers and engineers ever actually field tested the vents on real ceilings or walls, or if they only focused on drop in replacement floor vents? So unless you are are doing new construction, or have perfect paint and drywall, get ready for patching and painting. @@ -130,10 +130,10 @@ After a few days of having a few vents installed, I noticed that when closed som https://videopress.com/v/mjkR6GnH?resizeToParent=true&cover=true&preloadContent=metadata&useAverageColor=true Whistling vent -{{< gallery cols="1" >}} +{{< gallery cols="1" caption="Caulking gaps between vent and air duct" >}} {{< figure src="/media/2022/10/img%5F1675.jpg?w=545" alt="" caption="" >}} -{{< figure src="/media/2022/10/img%5F1684.jpg?w=768" alt="" caption="" >}}Caulking gaps between vent and air duct +{{< figure src="/media/2022/10/img%5F1684.jpg?w=768" alt="" caption="" >}} {{< /gallery >}} A day or so later I heard a familiar whistling noise again, and I found a vent that I did caulk and seal was now also whistling when closed. I removed the vent, double checked that it was properly caulked and sealed, it was. Thus this noise must be coming either from air blowing between the vent flange and the drywall, or from the screw slots on the long sides of the vent flange, or from the mechanical vent veins themselves. I can't do anything about noisy vent veins, but I can try to seal the flange. I applied some soft thin foam weatherstripping around the edge of the vent flange, creating a tight seal between the vent flange and the drywall, and also covering the unused and open flange screw holes. @@ -141,10 +141,10 @@ A day or so later I heard a familiar whistling noise again, and I found a vent t My initial attempt at using 3/8" thick foam from my local hardware store was unsuccessful, the foam compresses very well, but not enough to sit flush with the wall. I tried again using 1/4" thick [foam](https://amzn.to/3Sw5f8U), and that compressed well enough to seal the unused screw holes and sit flush with the drywall. -{{< gallery cols="1" >}} +{{< gallery cols="1" caption="Foam tape sealing around flange" >}} {{< figure src="/media/2022/10/img%5F1766.jpg?w=768" alt="" caption="" >}} -{{< figure src="/media/2022/10/img%5F1765.jpg?w=768" alt="" caption="" >}}Foam tape sealing around flange +{{< figure src="/media/2022/10/img%5F1765.jpg?w=768" alt="" caption="" >}} {{< /gallery >}} #### Flanges @@ -154,25 +154,25 @@ As I was patching and painting, I wondered if there wasn't an easier way to obsc I used [Fusion 360](https://www.autodesk.com/products/fusion-360/) to create a prototype flange for a 12x6 vent that could be laser cut from thin rigid plastic. -{{< gallery cols="1" >}} +{{< gallery cols="1" caption="Fusion360 flange design" >}} {{< figure src="/media/2022/10/6x12-v5-1-1.png?w=854" alt="" caption="" >}} {{< figure src="/media/2022/10/6x12-v5-2.png?w=1024" alt="" caption="" >}} -{{< figure src="/media/2022/10/2022-10-25-1.png?w=1024" alt="" caption="" >}}Fusion360 flange design +{{< figure src="/media/2022/10/2022-10-25-1.png?w=1024" alt="" caption="" >}} {{< /gallery >}} I looked for vendors with reasonable pricing and thin white paintable plastic material, [Xometry](https://www.xometry.com/) was too expensive, [SendCutSend](https://sendcutsend.com/) did not offer anything thinner than 3mm, so I used [Ponoko](https://www.ponoko.com/) to cut a 1.5mm thick White Acrylic flange. The 0.8mm White Delrin will be thinner but is more than double the price of 1.5mm White Acrylic. I received the piece in a bout a week, and as designed it is just a tad larger than the original vent to help cover edge damage. As I already did it the hard way by patching and painting, I did not use the flange in my own installation, but I did test fit it and it would have worked fine. -{{< gallery cols="4" >}} +{{< gallery cols="4" caption="Laser cut white acrylic flange" >}} {{< figure src="/media/2022/10/img_1708.jpg?w=726" alt="" caption="" >}} {{< figure src="/media/2022/10/img_1709.jpg?w=617" alt="" caption="" >}} {{< figure src="/media/2022/10/img_1752.jpg?w=601" alt="" caption="" >}} -{{< figure src="/media/2022/10/img_1751.jpg?w=519" alt="" caption="" >}}Laser cut white acrylic flange +{{< figure src="/media/2022/10/img_1751.jpg?w=519" alt="" caption="" >}} {{< /gallery >}} I shared the Fusion 360 projects and DXF files in [Autodesk Gallery](https://gallery.autodesk.com/projects/173188/flair-vent-flanges), and I created a shared [Ponoko cart](https://www.ponoko.com/share/MgBrJSraTWp83F79ob_Ql) with a ready to order 6x10 and 6x12 flange. For sizes other than 6x10 or 6x12 you will need to use Fusion 360 (free for hobby use) and adjust the dimensions in the sketch (\[modify\], \[change parameters\]), then export the projection as a DXF file. @@ -213,12 +213,12 @@ As winter approached it was getting colder at night, and one morning it was too Later the day I wondered how Flair will treat the different modes, and after I logged in I observed that the UI was confused, switching from red and heating mode one moment to blue and cooling mode the next. I verified that Ecobee was correct, heating downstairs and cooling upstairs, so something weird with Flair. In looking at the Flair UI one can see that there is only one operating mode reported, while each of the Ecobee thermostats can individually control heat/cool/auto/off modes. -{{< gallery cols="1" >}} +{{< gallery cols="1" caption="FLAIR is confused between heating and cooling" >}} {{< figure src="/media/2022/10/screen-shot-2022-10-24-at-11.42.47-am.png?w=1024" alt="" caption="" >}} {{< figure src="/media/2022/10/screen-shot-2022-10-24-at-10.26.47-am.png?w=1024" alt="" caption="" >}} -{{< figure src="/media/2022/10/screen-shot-2022-10-24-at-10.25.46-am.png?w=1024" alt="" caption="" >}}FLAIR is confused between heating and cooling +{{< figure src="/media/2022/10/screen-shot-2022-10-24-at-10.25.46-am.png?w=1024" alt="" caption="" >}} {{< /gallery >}} I posted my concern on the Flair [forum](https://support.flair.co/hc/en-us/community/posts/10111024260877-Flair-is-confused-when-one-system-is-on-heat-and-the-other-is-on-cool), and support responded that I have to create multiple logical homes if I want to run the units in different modes. This does not make sense, imagine I have multiple mini-split units, do I need to create a home for each mini-split? I contacted support directly, and they confirmed that all HVAC units must be set to the same mode. If this is a requirement, and the UI gets confused when not correctly set, I'd expect Flair to at least give a warning of an unsupported configuration. @@ -226,10 +226,10 @@ I posted my concern on the Flair [forum](https://support.flair.co/hc/en-us/commu With both Ecobee thermostats set back to Auto, I change the mode from within the Flair UI to Heat, expecting both Ecobees to switch to Heat mode. Instead the Ecobees switched to Heat and a Hold at 75°F, where 75°F seems to have been the current measured temperature. I had to manually remove the hold from both Ecobees to resume normal scheduled operation. This was again confusing and unexpected behavior. -{{< gallery cols="1" >}} +{{< gallery cols="1" caption="FLAIR changed the Ecobee mode to Heat and Hold" >}} {{< figure src="/media/2022/10/screenshot-2022-10-27-184203.png?w=1024" alt="" caption="" >}} -{{< figure src="/media/2022/10/screenshot-2022-10-27-184003.png?w=1024" alt="" caption="" >}}FLAIR changed the Ecobee mode to Heat and Hold +{{< figure src="/media/2022/10/screenshot-2022-10-27-184003.png?w=1024" alt="" caption="" >}} {{< /gallery >}} I have not yet tested Flair as setpoint controller, but for now I'll refrain from making any temperature changes from within the Flair app, and stick to using the Ecobee app. diff --git a/layouts/shortcodes/gallery.html b/layouts/shortcodes/gallery.html index 69be59a..155c409 100644 --- a/layouts/shortcodes/gallery.html +++ b/layouts/shortcodes/gallery.html @@ -1,5 +1,20 @@ +{{/* + A gallery of figures, optionally captioned as a set. + The container is a
    rather than a
    because
    is only valid as a + figure's child, and the caption describes the whole set rather than any one image. That + matches what the old platform emitted, a blocks-gallery-caption inside the gallery's own +
    , so a caption that came across as trailing text is restored to the element it + was. Attributing it to the last image instead would change what the post says. + + The reset already sets figure { margin: 0 }, and the theme styles figure > figcaption, so a + set caption inherits the site's caption appearance. It still needs one rule of its own, in + assets/css/extended/custom.css: the gallery is a flex container, so without a full-width + basis the caption packs onto the end of the last row and reads as a caption for whichever + image it lands beside. Do not remove that rule as redundant with the theme's. +*/}} {{ $p := .Page }} -
    +
    {{- print .Inner | $p.RenderString -}} -
    +{{- with .Get "caption" }}
    {{ . | $p.RenderString }}
    {{ end -}} +
    From 83966a5a1e1bd9711a81dfbe86bbb95bb3d3fe34 Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Sat, 8 Aug 2026 05:53:30 -0700 Subject: [PATCH 2/5] Record operations as recurring work, not as a finished milestone (#54) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Record operations as recurring work, not as a finished milestone The backlog listed the log review and the off-host log pull among the one-off migration tasks, so a reader finishing that list would read the migration as done while neither duty had ever run on its cadence. Both move to a Recurring operations section that says outright that everything above it ends and this does not, and the State table gains an Operations row so the summary stops implying the pipeline is the whole system. The open decision behind them is that the tooling has no home in git. vps-backup-pull, its systemd units, and the variables naming both ends of the copy exist only on the Proxmox host, which is the host the backup runs from, so losing it loses both the copies and the means of making them. Two candidate homes are recorded without choosing between them. The same question covers the fourteen migration scripts in the capture directory, and one of them already shows the cost of leaving it open: build-redirects.py exists in three places, the two capture copies identical to each other at 115 lines and this repo's maintained copy at 225. The capture is not a git repository, so nothing detects that. Two open questions are closed with measurements rather than assumptions. The production environment's HUGO_BASEURL held the live WordPress address, which the deploy workflow both builds with and points the live check at, and it is now the interim name. And the first production deploy does not fix the robots.txt 404 the VPS agent flagged in its 22.10: hugo.yaml sets no enableRobotsTXT so the site emits none at all, while sitemap.xml is emitted and becomes fetchable at that same deploy. The VPS production row said the resource was deliberately disabled, which its own file contradicted twenty lines later. Co-Authored-By: Claude Opus 5 (1M context) * Record the robots.txt cutover loss and the media gate gap The gallery caption entry under Open decisions is gone: #55 answered the question it posed, against the captured live site, and closed #52 with it. Two findings from the VPS agent's §23.3 and §24.3 replace it. The robots.txt entry described a gap on the interim name and missed that the cutover makes it a loss. The live .com blog serves a robots.txt today carrying a Sitemap: line, and this site emits none, so M7b moves a site that has had crawl directives for years to having none and takes the sitemap pointer with them. That side found it from the outside, will not put a file in this bundle, and has made it block step 1 of the M7b checklist rather than be discovered after it. Recorded as deliberately undecided with the three options, and Open decisions points at it rather than restating it, so the two cannot drift. Nothing checks that media survived the trip to the server. A 3,095-request gate run fetched no image at all, which prompted the question of whether the legacy media list is wired in. It is, at build time, against files on disk. The live check requests pages and redirects and never an image, so a media tree lost between the build and the server is caught by neither, the build having passed before the loss and the live gate never asking. Co-Authored-By: Claude Opus 5 (1M context) --------- Co-authored-by: Claude Opus 5 (1M context) --- TODO.md | 24 +++++++++++++++++++----- 1 file changed, 19 insertions(+), 5 deletions(-) diff --git a/TODO.md b/TODO.md index e419543..e65030c 100644 --- a/TODO.md +++ b/TODO.md @@ -17,7 +17,8 @@ The site is built, gated in CI, and deployed to staging by pipeline. It is not y | Fleet conformance | cataloged in the hub registry, audited, and carrying the current canonical | | Deploy pipeline | `deploy-site.yml` is dispatchable and has deployed staging from CI end to end | | VPS staging | live at `blog.vps.insanegenius.net`, behind the auth gate, serving a pipeline release | -| VPS production | environment configured, resource deliberately disabled, DNS still on the old platform | +| VPS production | reachable at `blog.insanegenius.net`, answering `200` unauthenticated, still serving `0000-placeholder`. DNS for the public name is still on the old platform | +| Operations | not started. Neither the periodic log review nor the off-host log pull has run on its cadence | ## Blocked on the maintainer @@ -30,16 +31,24 @@ The site is built, gated in CI, and deployed to staging by pipeline. It is not y - **Declare what the VPS keeps.** `hugo.deploy.retention` asks for a retention count declared at the destination, and this repo's deploy credential is write-only by design so the prune belongs to the host. The ownership is recorded in `OPERATIONS.md`, the count is not, and the "ten releases" beside it describes `deploy/make-release.sh` on the local mirrors rather than the containers on the VPS. Confirm the host's timer and its count, then write it next to the ownership line. - **Prove a rollback through the pipeline.** A forced mid-deploy failure, then a flip back to the previous release, verified by `EXPECT_RELEASE` rather than by the transport exiting zero. The server side has been measured at well under a second by hand; what is unproven is that a **pipeline** run leaves the site serving when its deploy fails part way. - **Deploy production once, to a name that is not the live one.** The host side is done and the interim name is live: `blog.insanegenius.net` answers `200` unauthenticated, on a Let's Encrypt certificate issued 2026-08-07, serving `0000-placeholder`. The VPS agent calls this M7a, and M7b is the `.com` cutover. Three items belong to this repo before the first production deploy, all detailed in the VPS agent's §19 and §20. That file is not in the repository, so pull it first per [`OPERATIONS.md`](./OPERATIONS.md) "The Channel Between the Two Sides": - - **Set `HUGO_BASEURL` to `https://blog.insanegenius.net` on the `production` environment**, and back to `.com` at M7b. Hugo bakes `baseURL` into the canonical tags, the feed, and `sitemap.xml`, so a deploy without this edit serves a site whose every absolute URL points at the live WordPress site. It works mechanically and it is wrong. + - **`HUGO_BASEURL` on the `production` environment is set to `https://blog.insanegenius.net/`**, done 2026-08-07. It held `https://blog.insanegenius.com/`, the live WordPress address, which is what the workflow both builds with and points the live check at, so a deploy would have baked the old platform's address into every canonical tag, feed link and `sitemap.xml` and then run 1,245 requests at the live site to verify it. **Setting it back to `.com` at M7b is the other half and is not done.** - **Production emits `X-Robots-Tag: noindex, nofollow` for the length of the rehearsal**, deliberately, because `.net` serves a public duplicate of a live site and Certificate Transparency publishes the hostname. Where a check asserts `index, follow`, make the expected value a parameter rather than flipping a literal, since it reverts at M7b and a hardcoded literal is one more thing to remember at the wrong moment. - - **Answer the two questions in §19.3**: what `HUGO_BASEURL` holds on `production`, and whether anything else in the build or the checks hardcodes `blog.insanegenius.com`. + - **The two questions in §19.3 are answered.** `HUGO_BASEURL` holds the interim `.net` name, per the item above. Exactly one place hardcodes `blog.insanegenius.com`: `baseURL` on line 1 of `hugo.yaml`, which is the production default every environment overrides through `HUGO_BASEURL`. Nothing under `checks/`, `deploy/`, `layouts/`, or `.github/` carries it. - **Decide what `robots.txt` says before the first production deploy.** Production answers 404 for it, so `X-Robots-Tag` is the only thing keeping the interim hostname out of an index. Crawlers are already asking: OAI-SearchBot, ClaudeBot, GPTBot, and Scrapy each arrived within three hours of the certificate being issued, at a hostname with no inbound links. + - **The first production deploy does not fix the 404, which is the part that reads the wrong way round.** The VPS agent raised this in §22.10 and asked two questions of this side. Both are now measured rather than assumed: **this site emits no `robots.txt` at all**, because `hugo.yaml` sets no `enableRobotsTXT`, so the 404 survives the deploy and `X-Robots-Tag` stays the only control. **`sitemap.xml` is emitted** and becomes fetchable on the interim name at that same deploy, listing whatever `HUGO_BASEURL` was built with, which is the second reason that variable mattered. Read together: after the rehearsal deploy a crawler gets a full sitemap and no robots file. + - **At the cutover this stops being a gap and becomes a loss, which is the half neither side had checked.** The live `.com` blog **serves a `robots.txt` today, carrying a `Sitemap:` line**. Since this site emits none, M7b is not a return to a previous state, it is a move from having crawl directives to having none on a site that has had them for years, and the sitemap pointer goes with them. The VPS agent measured this from the outside in §23.3, will not put a file in this repository's bundle, and has made it a decision that blocks step 1 of the M7b checklist rather than one discovered after it. The minimum that preserves today's behavior is `User-agent: *`, no `Disallow`, and the `.com` sitemap line, since every `Disallow` the old platform serves names a WordPress path this site does not have. **Deliberately undecided**, and the three options are to preserve today's behavior, to write what this site actually wants, or to keep emitting nothing and accept the loss. +- **Nothing checks that media survived the trip to the server.** The VPS agent noticed in §24.3 that a 3,095-request gate run fetched no image at all, and asked whether `golden-media-legacy.txt` is wired in. It is, but only at build time, in `check-url-parity.py`, against files on disk. The live check requests pages and redirects and never an image, so a media tree lost **between the build and the server**, a partial upload, is caught by neither: the build passed before the loss and the live gate never asks. On a site whose value is eighteen years of posts with images in them, that is the gap worth closing rather than the one that was suspected. A handful of media URLs in the live check would close it, chosen to cover both trees rather than to be exhaustive, since the build gate already proves the set. - Lower the `blog` A-record TTL to 60s a day ahead, then flip it to the VPS, unproxied. -- **"Backed up" describes a design rather than a fact, for the log.** The VPS holds the only copy of the access log until the pull to the backup host runs, and that log rotates and ages out on a schedule the host owns, so the window is the deadline. The pull is two rsync lines the maintainer adds on the backup host, and the log stays deliberately outside the nightly encrypted archives because those are full copies with no dedupe. State that plainly in anything built on top of the log until the pull runs. -- Watch server logs for non-200s daily for the first week, then monthly, because real traffic finds what the golden list missed and the crawl that produced the list cannot. Append anything new to `checks/golden-urls.txt` and add a redirect. Read the edge as well as Caddy: a request the proxy refused never reaches the site's log, so a count taken from Caddy alone is a floor. The procedure, the three tiers and what each is blind to, and the inward pass that names content nobody has ever requested are in [`OPERATIONS.md`](./OPERATIONS.md) "Log Review". - Add the weekly non-blocking external-link-check workflow, which is the one gate that cannot be blocking because it fails on other people's outages. - Decommission WordPress.com only after **30 clean days**, and downgrade to free rather than deleting, which keeps the media reachable as a safety net and preserves the ability to re-export. Do not start sooner: the conversion fetched media over HTTP from the live site. +## Recurring operations + +**Everything above ends; this section does not.** The list above finishes when the site serves its public address, and these two start there and never stop. Both are written down as procedures and neither has run on its cadence yet, which is the shape a recurring duty has right before it silently becomes a one-off. An end-to-end exercise of this system is a deploy **plus** the operations that follow it, so a run that proves staging and production and stops has proven the half that has an obvious finish line. + +- **Review the logs for non-200s**, daily for the first week after cutover, then monthly. Real traffic finds what the golden list missed and the crawl that produced the list cannot. Append anything new to `checks/golden-urls.txt` and add a redirect. Read the edge as well as Caddy: a request the proxy refused never reaches the site's log, so a count taken from Caddy alone is a floor, and a staging probe for `/wp-login.php` answered by the auth gate rather than by the site is the shape of what Caddy never sees. The procedure, the three tiers and what each is blind to, and the inward pass that names content nobody has ever requested are in [`OPERATIONS.md`](./OPERATIONS.md) "Log Review". +- **Pull the log off the VPS, on a schedule**, which is [#53][issue-53]. The access log is deliberately outside the nightly encrypted archives, because those are fourteen full copies with no dedupe and an append-only file would be multiplied by fourteen for no recovery benefit. So the VPS's 400-day window is the **only** copy until this runs. The two rsync lines are now written, parameterized, and tested against the live host, and they are not installed, because installing needs root. **Until they are, say plainly that "backed up" describes a design rather than a fact in anything built on top of that log.** + ## Owed to the hub Nothing. The spec update this repo owed the hub has landed: [ProjectTemplate#560][hub-type-pr] authored the `hugo` type, the `self-hosted` target, the `deploy-ssh` mechanism, guarantees D4.6 and D5.6, and a reference leaf pair, all measured from what this repo actually runs rather than from the prediction the intake carried. [#456][hub-issue] and [#558][hub-spec-issue] are closed with it. @@ -55,6 +64,10 @@ The reference leaf the hub now ships carries one step this repo's deploy does no ## Open decisions +- **Where the operational tooling lives, given that today it lives nowhere.** `vps-backup-pull`, its `systemd` units, and the environment variables naming both ends of the copy are an operational asset built from another agent's instructions, and they exist only on the Proxmox host. That host is the machine the backup runs *from*, so losing it loses both the copies and the means of making them, and the instructions that produced them are in a channel file this repository deliberately does not carry. Two candidate homes, and the choice is open: **here**, beside the deploy tooling the same host runs, or **the home-automation config repository**, with the rest of that host's configuration. The argument for the second is that nothing about the pull is specific to this site; the argument for the first is that [`OPERATIONS.md`](./OPERATIONS.md) "Log Review" is the thing that stops working without it. + - **The same question covers the migration toolchain in the capture directory**, which is fourteen scripts: the `wp2hugo` run, the content restructure and clean passes, external-media localization, the crawl and mirror, the golden-URL build, and the media inventory. Some are worth keeping only if generalized, and some are cheaper to rewrite than to maintain, so this is a per-script call rather than one decision. + - **One of them is already three copies with two of them stale**, which is the concrete version of this risk rather than a hypothetical one. `build-redirects.py` exists at the capture root, again under the capture's own `checks/`, and here at [`checks/build-redirects.py`](./checks/build-redirects.py). The two capture copies are identical to each other at 115 lines; the copy in this repository is the maintained one at 225. Nothing detects that, because the capture is not a git repository and is read-only in normal use. +- **What `robots.txt` says, which is undecided and is the last non-mechanical item before M7b.** Recorded under "Next" above, where it blocks the cutover. - `/robots.txt/` and `/osd.xml/` currently sit in `slugs.map` pointing at `/`. The first would be better pointing at the real `/robots.txt`. - Content is capped at a fixed 720px on every screen, because PaperMod's width is four CSS variables with no responsive term and no Hugo parameter. The prose measure is right and should stay; images and galleries inheriting the same cap is the part that costs something on a wide display. The knobs, the override location, and the `--gap` trap are documented under "Customization points" in [`themes/README.md`](./themes/README.md). @@ -148,6 +161,7 @@ The deploy root is deliberately absent from this table. The rsync destination is [issue-33]: https://github.com/ptr727/Blog/issues/33 +[issue-53]: https://github.com/ptr727/Blog/issues/53 [migration-post]: ./content/posts/2026/08/01/moving-this-blog-from-wordpress-to-hugo.md [pr-30]: https://github.com/ptr727/Blog/pull/30 [pr-40]: https://github.com/ptr727/Blog/pull/40 From bb1ed2f486b27f1087adc16b157cc1533ba79f89 Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Sat, 8 Aug 2026 06:36:42 -0700 Subject: [PATCH 3/5] Record the transport retest, retire the #33 entry, and hold the main publish (#37) * Record the transport retest and what #33 still owes * Retire the #33 entry and hold the main publish for the soak The retest issue closes on the prerelease dispatch rather than on a production deploy, so the entry naming a production deploy as its fourth check is answered rather than outstanding. #33 has since closed, on 2026-08-06, which confirms it. The main publish is added as its own item, gated on the soak rather than on the mechanism, which is proven. 1.0.11 is still the newest release from main and still predates every deploy change, so the next release from main is the first that would describe a site serving its public address. Rebased onto develop and reconciled with what landed while this sat open. The hub row this branch added for ProjectTemplate#567 is dropped. That issue closed on 2026-08-05, a day before this branch was last touched, so the row was already wrong when written. Its claim has since been falsified outright: it said an agent cannot trip the production ref gate because the permission classifier refuses a production-labeled dispatch, and a production deploy was dispatched and completed on 2026-08-08. The `Deploy production once` bullet keeps develop's version rather than this branch's. This branch still described that environment as never having run, and it has now served a release. The `Declare what the VPS keeps` bullet goes, which the earlier commit dropped without saying why. It asked for the host's timer and its count to be written beside the ownership line, and `OPERATIONS.md` now names `blog-prune-releases.timer`, that it runs daily, and that it keeps ten bundles per environment. The item is answered rather than abandoned. The main publish item pointed at "the daily 404 watch above", which moved below it into Recurring operations, so it names that section instead. A pointer by position is the same defect a review already flagged on this branch once. Co-Authored-By: Claude Opus 5 (1M context) --------- Co-authored-by: Claude Opus 5 (1M context) --- TODO.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/TODO.md b/TODO.md index e65030c..bbaf6e1 100644 --- a/TODO.md +++ b/TODO.md @@ -15,7 +15,7 @@ The site is built, gated in CI, and deployed to staging by pipeline. It is not y | GitHub repo | public, both rulesets active, `configure.sh check` exits 0 | | Release pipeline | proven end to end. `1.0.17-g4b2def3ee9` is the newest, a prerelease from `develop` | | Fleet conformance | cataloged in the hub registry, audited, and carrying the current canonical | -| Deploy pipeline | `deploy-site.yml` is dispatchable and has deployed staging from CI end to end | +| Deploy pipeline | `deploy-site.yml` is dispatchable and has deployed staging from CI end to end, through a transport retested against the real host | | VPS staging | live at `blog.vps.insanegenius.net`, behind the auth gate, serving a pipeline release | | VPS production | reachable at `blog.insanegenius.net`, answering `200` unauthenticated, still serving `0000-placeholder`. DNS for the public name is still on the old platform | | Operations | not started. Neither the periodic log review nor the off-host log pull has run on its cadence | @@ -27,8 +27,6 @@ The site is built, gated in CI, and deployed to staging by pipeline. It is not y ## Next, in dependency order -- **Retest the deploy transport against the real host**, which is [#33][issue-33] and is joint work with whoever holds the server. The transport now pins `StrictHostKeyChecking`, `UserKnownHostsFile`, and `BatchMode`, so it fails closed where it previously failed open, and a stale `DEPLOY_SSH_KNOWN_HOSTS` stops a deploy rather than being tolerated. Staging first, since a broken transport blocks the rollback path as well as the deploy. -- **Declare what the VPS keeps.** `hugo.deploy.retention` asks for a retention count declared at the destination, and this repo's deploy credential is write-only by design so the prune belongs to the host. The ownership is recorded in `OPERATIONS.md`, the count is not, and the "ten releases" beside it describes `deploy/make-release.sh` on the local mirrors rather than the containers on the VPS. Confirm the host's timer and its count, then write it next to the ownership line. - **Prove a rollback through the pipeline.** A forced mid-deploy failure, then a flip back to the previous release, verified by `EXPECT_RELEASE` rather than by the transport exiting zero. The server side has been measured at well under a second by hand; what is unproven is that a **pipeline** run leaves the site serving when its deploy fails part way. - **Deploy production once, to a name that is not the live one.** The host side is done and the interim name is live: `blog.insanegenius.net` answers `200` unauthenticated, on a Let's Encrypt certificate issued 2026-08-07, serving `0000-placeholder`. The VPS agent calls this M7a, and M7b is the `.com` cutover. Three items belong to this repo before the first production deploy, all detailed in the VPS agent's §19 and §20. That file is not in the repository, so pull it first per [`OPERATIONS.md`](./OPERATIONS.md) "The Channel Between the Two Sides": - **`HUGO_BASEURL` on the `production` environment is set to `https://blog.insanegenius.net/`**, done 2026-08-07. It held `https://blog.insanegenius.com/`, the live WordPress address, which is what the workflow both builds with and points the live check at, so a deploy would have baked the old platform's address into every canonical tag, feed link and `sitemap.xml` and then run 1,245 requests at the live site to verify it. **Setting it back to `.com` at M7b is the other half and is not done.** @@ -39,6 +37,7 @@ The site is built, gated in CI, and deployed to staging by pipeline. It is not y - **At the cutover this stops being a gap and becomes a loss, which is the half neither side had checked.** The live `.com` blog **serves a `robots.txt` today, carrying a `Sitemap:` line**. Since this site emits none, M7b is not a return to a previous state, it is a move from having crawl directives to having none on a site that has had them for years, and the sitemap pointer goes with them. The VPS agent measured this from the outside in §23.3, will not put a file in this repository's bundle, and has made it a decision that blocks step 1 of the M7b checklist rather than one discovered after it. The minimum that preserves today's behavior is `User-agent: *`, no `Disallow`, and the `.com` sitemap line, since every `Disallow` the old platform serves names a WordPress path this site does not have. **Deliberately undecided**, and the three options are to preserve today's behavior, to write what this site actually wants, or to keep emitting nothing and accept the loss. - **Nothing checks that media survived the trip to the server.** The VPS agent noticed in §24.3 that a 3,095-request gate run fetched no image at all, and asked whether `golden-media-legacy.txt` is wired in. It is, but only at build time, in `check-url-parity.py`, against files on disk. The live check requests pages and redirects and never an image, so a media tree lost **between the build and the server**, a partial upload, is caught by neither: the build passed before the loss and the live gate never asks. On a site whose value is eighteen years of posts with images in them, that is the gap worth closing rather than the one that was suspected. A handful of media URLs in the live check would close it, chosen to cover both trees rather than to be exhaustive, since the build gate already proves the set. - Lower the `blog` A-record TTL to 60s a day ahead, then flip it to the VPS, unproxied. +- **Publish a release from `main`, once the pipeline has soaked.** `1.0.11` is the newest release from `main` and was cut on 2026-08-01, ahead of every deploy change, so the next one is the first that would describe a site actually serving its public address. The mechanism is proven and is not what this waits on: it waits on the switchover being trusted rather than merely green, which is what the log review under **Recurring operations** establishes and no gate can. A release cut before that names a state that has not held yet. - Add the weekly non-blocking external-link-check workflow, which is the one gate that cannot be blocking because it fails on other people's outages. - Decommission WordPress.com only after **30 clean days**, and downgrade to free rather than deleting, which keeps the media reachable as a safety net and preserves the ability to re-export. Do not start sooner: the conversion fetched media over HTTP from the live site. @@ -160,7 +159,6 @@ The deploy root is deliberately absent from this table. The rsync destination is -[issue-33]: https://github.com/ptr727/Blog/issues/33 [issue-53]: https://github.com/ptr727/Blog/issues/53 [migration-post]: ./content/posts/2026/08/01/moving-this-blog-from-wordpress-to-hugo.md [pr-30]: https://github.com/ptr727/Blog/pull/30 From 466bf43e47b248a1c32b473ecc15586b83d8cf63 Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Sat, 8 Aug 2026 06:37:26 -0700 Subject: [PATCH 4/5] Record media integrity in the State table (#48) The table said nothing about whether the conversion lost anything, which is the one question a migration's record has to answer and the one a reader cannot check for themselves. Rebased onto develop and reconciled with two things that landed while this sat open. The volatile counts it originally carried in the Content and media row are gone, because develop deliberately replaced counts that content additions move with what they represent, and this row would have reintroduced 514 pages against that decision. And the claim is narrowed from "closed" to closed for the files themselves: the image loss was 19 and is restored, but #55 later found the conversion had also flattened how galleries present media, in three shapes across three posts. That was not a file loss and no file was missing, which is exactly why nothing saw it for so long, and it is now gated. Co-authored-by: Claude Opus 5 (1M context) --- TODO.md | 1 + 1 file changed, 1 insertion(+) diff --git a/TODO.md b/TODO.md index bbaf6e1..b2e2114 100644 --- a/TODO.md +++ b/TODO.md @@ -9,6 +9,7 @@ The site is built, gated in CI, and deployed to staging by pipeline. It is not y | Piece | State | | --- | --- | | Content and media | done. Carries every migrated post and page, with the media hash-verified against the export tar | +| Media integrity | closed for the files themselves. The conversion's only loss was 19 images, inside five galleries, restored from the capture, and the 98 files with no page links are adjudicated rather than unknown, with `ORPHANED_MEDIA` failing if that count moves either way. How media was *presented* was a separate loss, found later and now gated | | URL contract | done. 328 render, 917 redirect, 778 legacy image URLs, all gated | | Deploy shape | done. Proven on two local mirrors and on the VPS, by hand and by pipeline | | CI workflows | green. Validation runs on every pull request and feeds the required check | From 7b1f8ffa06939ceda5a184d26dd437995f01e4ac Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Sat, 8 Aug 2026 06:54:37 -0700 Subject: [PATCH 5/5] Record M7a as done, since production is serving a release (#57) Found by review on the promotion #56, which caught the file contradicting the description of its own promotion. The State table and the dependency list both still said production served 0000-placeholder and that the first deploy was pending. It deployed on 2026-08-08 and serves 20260808-041050. Three places said it, and all three are now what was measured rather than what was expected. The State row records the release and that the host side verified it independently, 9/9 unauthenticated with the built baseURL read from the deployed bytes rather than from this repo's config, across a 3,095-request gate run. The production item leads with M7a done and reframes its sub-items as where this repo stands against M7b, two owed and one answered, rather than as work before a first deploy that has happened. And the robots decision is now before the cutover rather than before the first deploy, with its 404 measured after the deploy rather than predicted before it. Co-authored-by: Claude Opus 5 (1M context) --- TODO.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/TODO.md b/TODO.md index b2e2114..75cfb40 100644 --- a/TODO.md +++ b/TODO.md @@ -18,7 +18,7 @@ The site is built, gated in CI, and deployed to staging by pipeline. It is not y | Fleet conformance | cataloged in the hub registry, audited, and carrying the current canonical | | Deploy pipeline | `deploy-site.yml` is dispatchable and has deployed staging from CI end to end, through a transport retested against the real host | | VPS staging | live at `blog.vps.insanegenius.net`, behind the auth gate, serving a pipeline release | -| VPS production | reachable at `blog.insanegenius.net`, answering `200` unauthenticated, still serving `0000-placeholder`. DNS for the public name is still on the old platform | +| VPS production | **M7a done 2026-08-08.** Serving release `20260808-041050` at `blog.insanegenius.net`, answering `200` unauthenticated, verified 9/9 from the host side with the built `baseURL` read from the deployed bytes. DNS for the public name is still on the old platform | | Operations | not started. Neither the periodic log review nor the off-host log pull has run on its cadence | ## Blocked on the maintainer @@ -29,12 +29,12 @@ The site is built, gated in CI, and deployed to staging by pipeline. It is not y ## Next, in dependency order - **Prove a rollback through the pipeline.** A forced mid-deploy failure, then a flip back to the previous release, verified by `EXPECT_RELEASE` rather than by the transport exiting zero. The server side has been measured at well under a second by hand; what is unproven is that a **pipeline** run leaves the site serving when its deploy fails part way. -- **Deploy production once, to a name that is not the live one.** The host side is done and the interim name is live: `blog.insanegenius.net` answers `200` unauthenticated, on a Let's Encrypt certificate issued 2026-08-07, serving `0000-placeholder`. The VPS agent calls this M7a, and M7b is the `.com` cutover. Three items belong to this repo before the first production deploy, all detailed in the VPS agent's §19 and §20. That file is not in the repository, so pull it first per [`OPERATIONS.md`](./OPERATIONS.md) "The Channel Between the Two Sides": +- **Production is deployed, which the VPS agent calls M7a, done 2026-08-08.** `blog.insanegenius.net` serves release `20260808-041050`, answering `200` unauthenticated on a Let's Encrypt certificate issued 2026-08-07. The host side verified it independently, 9/9 unauthenticated with the built `baseURL` read from the deployed bytes rather than from this repo's config, across a 3,095-request gate run with no unexplained 404s. What remains is **M7b, the `.com` cutover**, and the sub-items below are where this repo stands against it, two of them owed and one already answered. The VPS agent's §19, §20, §23 and §24 carry the detail and that file is not in the repository, so pull it first per [`OPERATIONS.md`](./OPERATIONS.md) "The Channel Between the Two Sides": - **`HUGO_BASEURL` on the `production` environment is set to `https://blog.insanegenius.net/`**, done 2026-08-07. It held `https://blog.insanegenius.com/`, the live WordPress address, which is what the workflow both builds with and points the live check at, so a deploy would have baked the old platform's address into every canonical tag, feed link and `sitemap.xml` and then run 1,245 requests at the live site to verify it. **Setting it back to `.com` at M7b is the other half and is not done.** - **Production emits `X-Robots-Tag: noindex, nofollow` for the length of the rehearsal**, deliberately, because `.net` serves a public duplicate of a live site and Certificate Transparency publishes the hostname. Where a check asserts `index, follow`, make the expected value a parameter rather than flipping a literal, since it reverts at M7b and a hardcoded literal is one more thing to remember at the wrong moment. - **The two questions in §19.3 are answered.** `HUGO_BASEURL` holds the interim `.net` name, per the item above. Exactly one place hardcodes `blog.insanegenius.com`: `baseURL` on line 1 of `hugo.yaml`, which is the production default every environment overrides through `HUGO_BASEURL`. Nothing under `checks/`, `deploy/`, `layouts/`, or `.github/` carries it. -- **Decide what `robots.txt` says before the first production deploy.** Production answers 404 for it, so `X-Robots-Tag` is the only thing keeping the interim hostname out of an index. Crawlers are already asking: OAI-SearchBot, ClaudeBot, GPTBot, and Scrapy each arrived within three hours of the certificate being issued, at a hostname with no inbound links. - - **The first production deploy does not fix the 404, which is the part that reads the wrong way round.** The VPS agent raised this in §22.10 and asked two questions of this side. Both are now measured rather than assumed: **this site emits no `robots.txt` at all**, because `hugo.yaml` sets no `enableRobotsTXT`, so the 404 survives the deploy and `X-Robots-Tag` stays the only control. **`sitemap.xml` is emitted** and becomes fetchable on the interim name at that same deploy, listing whatever `HUGO_BASEURL` was built with, which is the second reason that variable mattered. Read together: after the rehearsal deploy a crawler gets a full sitemap and no robots file. +- **Decide what `robots.txt` says, now before the cutover rather than before the first deploy.** Production answers 404 for it, so `X-Robots-Tag` is the only thing keeping the interim hostname out of an index. Crawlers are already asking: OAI-SearchBot, ClaudeBot, GPTBot, and Scrapy each arrived within three hours of the certificate being issued, at a hostname with no inbound links. + - **The deploy did not fix the 404, which is the part that reads the wrong way round, and is now measured rather than predicted.** The VPS agent raised this in §22.10 and asked two questions of this side. Both are now measured rather than assumed: **this site emits no `robots.txt` at all**, because `hugo.yaml` sets no `enableRobotsTXT`, so the 404 survives the deploy and `X-Robots-Tag` stays the only control. **`sitemap.xml` is emitted** and becomes fetchable on the interim name at that same deploy, listing whatever `HUGO_BASEURL` was built with, which is the second reason that variable mattered. Read together: after the rehearsal deploy a crawler gets a full sitemap and no robots file. - **At the cutover this stops being a gap and becomes a loss, which is the half neither side had checked.** The live `.com` blog **serves a `robots.txt` today, carrying a `Sitemap:` line**. Since this site emits none, M7b is not a return to a previous state, it is a move from having crawl directives to having none on a site that has had them for years, and the sitemap pointer goes with them. The VPS agent measured this from the outside in §23.3, will not put a file in this repository's bundle, and has made it a decision that blocks step 1 of the M7b checklist rather than one discovered after it. The minimum that preserves today's behavior is `User-agent: *`, no `Disallow`, and the `.com` sitemap line, since every `Disallow` the old platform serves names a WordPress path this site does not have. **Deliberately undecided**, and the three options are to preserve today's behavior, to write what this site actually wants, or to keep emitting nothing and accept the loss. - **Nothing checks that media survived the trip to the server.** The VPS agent noticed in §24.3 that a 3,095-request gate run fetched no image at all, and asked whether `golden-media-legacy.txt` is wired in. It is, but only at build time, in `check-url-parity.py`, against files on disk. The live check requests pages and redirects and never an image, so a media tree lost **between the build and the server**, a partial upload, is caught by neither: the build passed before the loss and the live gate never asks. On a site whose value is eighteen years of posts with images in them, that is the gap worth closing rather than the one that was suspected. A handful of media URLs in the live check would close it, chosen to cover both trees rather than to be exhaustive, since the build gate already proves the set. - Lower the `blog` A-record TTL to 60s a day ahead, then flip it to the VPS, unproxied.