Field note 1 — Building this site with the guidance itself

Original to this site (not upstream content). Written from the build logs of this project, 2026-11-12.

This site is also the pilot for installing the Modern Web Guidance as an agent skill. Three measured findings came out of that pilot:

1. The installer hangs in non-interactive shells unless you pass --yes

npx -y modern-web-guidance@latest install looks non-interactive but isn’t: the installer’s own multi-select prompt (“Which agents do you want to install to?”, 79 agents) waits forever — our run timed out at 120 seconds having written nothing. The fix is one flag on the tool itself, install --yes, which completed in about 16 seconds and wrote only inside the project (.agents/skills/modern-web-guidance/, about 2.3 MB, plus skills-lock.json). Lesson: npx -y answers npm’s question, not the tool’s.

A second trap: the installer’s retrieve command rewrites GUIDE_REF macros in guide text into “(via npx … retrieve …)” hints. Fine for an agent, wrong for a publisher — this site converts from the repository files, never from retrieve output.

2. A 390px viewport, not features, chose the framework

We built the same 8 hardest guides on two bases (Starlight and a plain Astro template). Builds, canonical URLs, sitemaps and search indexes were equivalent. The only decisive difference: at a real 390px window width, the framework base passed 9/9 pages with no horizontal overflow, while the hand-rolled template overflowed on 9/9 (scroll width 494–1073px) because of a fixed 240px sidebar and zero responsive rules. One methodological warning from that test: emulating a device with CDP setDeviceMetricsOverride silently widened the layout viewport and hid the overflow; launching the browser with --window-size=390,844 gave trustworthy numbers.

3. Conversion is a pipeline problem, not a writing problem

All 252 upstream guides were converted by one script. The work is in the edge cases: 8 guides carry upstream draft flags and are excluded; several are frontmatter-only stubs with no body at all; cross-reference macros point at guides that may not be published yet, so links must degrade to plain text instead of 404s; and every page would have had two H1 elements (the template renders the title, the markdown also starts with one) until the converter learned to strip the first heading. None of this is visible when you convert eight sample pages — it all appears at 252.