PR #1409 — Giving the Book a Brand, Without Breaking Its Spine
The Broader Goal at the End of the Previous PR
Draft v0.5 of "The Supervised Machine" had just absorbed the Strategic Review integration — new chapters, deep-dive expansions, the pre-Part-0 cold open — landing it at its most structurally complete state yet. The goalpost at the end of that work was editorial: the book's content was right. Its presentation was an afterthought — Georgia serif, ad hoc grays and golds, nothing tying it visually to synlynk itself.
Strategic Shifts in This PR
The trigger was simple: the manuscript didn't look like it came from the same project as the Synlynk Quick Start Guide and Manual, both of which share a deliberate brand system (Inter + JetBrains Mono, a fixed color-token palette, terminal-block styling, pill badges). The instinct might have been to port that system wholesale — but the Quick Start/Manual layout is built on fixed-height A4 "slide" pages with overflow:hidden, designed for short curated docs where every page is hand-fit to its content. The book is ~30,000 words of flowing narrative prose across 19 chapters. Forcing it into that mechanic would silently clip or truncate text.
Presented with that trade-off directly, the call was: keep the book's natural flowing, print-media pagination (page-break-before/after, no fixed heights), and layer the brand's visual language on top of it — fonts, palette, cover treatment, section labels, callout and terminal styling, page-header chrome. Brand skin, not brand skeleton.
Mid-implementation, a second-order risk surfaced: a separate, directly-authored PR (#1411) had independently restyled the same file using the opposite, previously-rejected layout choice — strict fixed-height A4 slides, plus a new Puppeteer npm dependency for PDF generation. Two PRs solving the same problem with incompatible designs is exactly the kind of redundant/conflicting work this project's dispatch discipline exists to catch. The resolution: keep the flowing-layout PR (#1409), close #1411 with an explanation (branch left intact, not deleted, since the Puppeteer PDF-pipeline idea has independent merit worth revisiting separately), and clean up the node_modules/ #1411's npm install had left behind in the main worktree.
What This PR Shipped
The restyle itself was dispatched to Codex (job-ff609558, based explicitly off origin/main to avoid a documented stale-branch-basing pitfall), scoped to touch only the <style> block of the-supervised-machine-v0.5-DRAFT.html — a 73-line-addition/38-line-deletion diff, with the manuscript content outside <style> verified byte-for-byte unchanged against HEAD. It adopted the shared brand :root token set (--blue, --purple, --green, --bg, --text, etc.), Inter/JetBrains Mono typography, the gradient cover accent bar, uppercase-letterspaced "kicker" section labels, and the terminal/callout card styling from the Quick Start guide — while leaving the print-media pagination model exactly as the design decision called for.
The one piece the dispatch job couldn't finish: regenerating the tracked PDF. Headless Chrome inside the dispatch sandbox aborted with SIGABRT (HIServices _RegisterApplication → TransformProcessType, an SCClientSession/CoreServicesd XPC check-in failure) on even about:blank — a macOS sandbox restriction, not a content bug. This is the same crash signature independently reported from a different, unrelated session around the same time, which turned out to trace back to #1411's Puppeteer-based Chrome invocation rather than this dispatch. Per this project's PM/reviewer split, this was native (non-dispatched) work: the PDF was regenerated locally with real, unsandboxed Chrome using the documented command in docs/book/README.md, then committed as a follow-up on the dispatch branch. pdffonts confirmed Inter and JetBrains Mono variants (Regular, Bold, SemiBold, ExtraBold) actually embedded as subsetted Type 3 fonts with Unicode mapping — ruling out a silent fallback to a system serif, which an initial low-resolution pdftoppm preview render had misleadingly suggested (a Poppler Type-3-glyph rendering artifact, resolved at 150dpi).
Review followed the project's identity-sharing fallback (#423): since all dispatched harnesses share one GitHub identity, self-approval isn't possible, so verification was posted as a formal gh pr review --comment covering the scoped diff, the preserved pagination model, the visually-verified brand adoption (cover, TOC, a chapter opener, a part divider, a body page with inline code and callouts), and the PDF font-embedding check. Merge required qa-role authority per .synlynk/policy.json's merge_authority; branch protection then required an approving (not comment) review that the shared identity structurally can't produce, so the merge used the disclosed --admin fallback rather than working around the protection silently.
Brainstorm Visuals Used
None directly — the design decision (flowing pages, brand skin) was resolved through a direct trade-off question rather than a visual brainstorm session.
What This Achieved on the Path to Autonomy
This is a small but concrete instance of the project's redundant-work detection working as intended: two independently-produced PRs targeting the same file were caught and reconciled via direct GitHub inspection (gh pr list/gh pr view) rather than either job's self-reported status, consistent with this project's standing "never trust job status alone" discipline. It's also another data point for the identity-sharing caveat from #423 — every merge on a dispatch- or Claude-authored PR in this repo is going to keep needing either a comment-review fallback plus qa-role sign-off, or an explicit --admin override, until GitHub App-scoped identities per role actually land.
Strategic Note: The Goal at the End of This PR
The book now visually belongs to the same project as its own documentation, without sacrificing the long-form reading experience a 30k-word manuscript needs. The next goalpost is narrower: a real (non-Puppeteer-sandbox-fighting) PDF regeneration story that doesn't depend on a human running real Chrome locally every time the HTML changes — the problem #1411 was reaching for, now scoped as its own follow-up rather than bundled into the brand restyle.