Home / Engineering notes / These sites
Public site engineering notes
What was learned while designing the pages of oblivios.org.
What was learned while designing the pages of oblivios.org: how to show a page to the owner, how the prints are drawn, and what broke. The design record is ADR-251; the sources are in ../design/oblivios-org-2026-11-17/.
1Showing a page to the owner
- The in-app browser pane opens a
file://page as a static snapshot (2026-11-17): scripts do not run and neither a relative image nor afile://image loads. The owner saw a broken logo and no hero picture on such a page, and no header link, which were reported as "no image" and "no header". Embed assets asdata:URIs (the generator does) and serve the output over HTTP for anything with a script. - Serving:
python3 -m http.server 8123 --bind 127.0.0.1 -d <out>in the background, then open it withpreview_startand itsurlargument. A firstnavigateto the127.0.0.1address was denied;preview_startwith the sameurlopened it, andnavigateworked afterwards in that tab. Kill the server at the end of the session (the process list showspython3 -m http.server 8123). - The editor tool opens every written HTML file in the pane as a
file://tab ("is now visible in the Browser pane"). The tabs pile up and show the broken snapshot. Tell the owner which tab is the served one. - The pane width was 798 px in the first reports and 1630 px later. A first build with a fixed width of 1440 px put the hero picture at x = 755 in the 798 px pane, so the owner saw text only. Build fluid from the start and read it at 390, 798, 1440 and 1920 px.
- Headless Chromium renders any width:
chromium --headless --no-sandbox --disable-gpu --hide-scrollbars --window-size=W,H --screenshot=OUT URL. Append?norvto the URL to hide the review layer. The screenshot has the window height, so choose H above the page height and crop. - Overflow check run in the page, per width:
document.documentElement.scrollWidthagainstinnerWidth, and the elements whosegetBoundingClientRect().rightexceedsinnerWidth(ignore the hidden defssvg, the review layer andpreblocks, which scroll by design). All pages showed zero on 2026-11-17 at 798 px and at 1630 px for Status, Security and FAQ. - Link check over the generated files: every
hrefthat is not external must name a generated page, and a#fragmentmust be anidon that page. 182 links, none broken, 2026-11-17.
2Click-to-flag review
review.js is the review layer. A pill switches it on; a click flags the element under the pointer (red outline, a number, a note field) and a second click removes the flag; links are intercepted while it is on. Flags are saved per page in localStorage under rv:<path> and are read back with window.__allFlags() through the browser tool's JavaScript on the served tab. The owner flagged 7, 7, 1, 9 and 1 elements in five rounds and wrote a reason on most. Read the flags first, then clear them (localStorage.removeItem per rv: key) so that old badges do not sit on the rebuilt page. A reason that says only that something is not good is answered by asking which part; the flag itself names the element.
3Prints (SVG)
- One filter (
feTurbulenceplusfeDisplacementMapfor a warped edge, a second turbulence thresholded byfeColorMatrixandfeCompositefor the speckle holes) and one gradient per canvas give every print the look of the logo: grey at the edges, brick red in the centre. A misprint shadow is the same print in brick red, offset by 6 and 5 units, blended withmultiply. The turbulence frequencies are in user units, so a print drawn on a larger canvas has finer grain. - Prints are defined once in a hidden
svgand placed with<use>. A cloned element takes its inheritable properties from theuseelement, and a CSS selector that depends on an ancestor of theuse(.alt .pp) does not match the clone. The hole colour of the details is thereforevar(--hole), set on the band; custom properties do inherit into the clone. - A group whose bounding box has no height (a lone horizontal dotted line) is not drawn when an object-bounding-box filter is applied to it. Put such a line in a group with the other shapes of the print, or draw it in CSS.
- Gradients use
userSpaceOnUse: 0 to 200 for a single plate and 0 to 1000 for the chain, whose five prints are cut out of one canvas with aviewBoxofx 40 200 200. - A speckle threshold that is too low gives a stippled look; the logo has crisp edges with few holes. The values in the filter (
22 0 0 0 -6.1) are the second try.
4Layout
.prose poutranks a plain class on a paragraph; a styled paragraph inside prose needs.prose p.<class>.details::details-contentwithinterpolate-size: allow-keywordsanimates the FAQ in Chromium; other engines open the answer at once, which is the fallback.- A bar of accepted against proposed decisions is a
divwith two widths and a text equivalent in anaria-label.
5The Astro build of oblivios.org (2026-11-17)
Layout and commands are in site/README.md. What was learned and measured on the first day:
- Under
Content-Security-Policy: default-src 'self'an inline<style>, astyleattribute and adata:URI are blocked, and the mockups used all three. The build therefore setsbuild.inlineStylesheets: "never"andvite.build.assetsInlineLimit: 0, draws SVG widths as attributes (stroke-width="15", a bar is ansvgofrectelements), keeps the grain, the stamp mask and the logo mask as files insite/shared/public/, andscripts/check-build.mjsfails on any of them in the output. scripts/serve.mjsservesdist/with the headers andcleanUrlsofvercel.json;--axeserves axe-core at/__axe.js;--reviewleaves the policy off because the review layer injects a stylesheet and uses local storage.build:review(REVIEW=1) is the only build that contains it; the check fails whenreview.jsor storage access is in a production output. The server must start insite/org(it readsdistandvercel.jsonfrom the working directory);npm --prefix <site> run serve -w org -- --port Ndoes that. axe-core sits insite/node_modules(hoisted), not insite/org/node_modules.- A tool call that adds a
<style>to a page served with the policy is silently refused: switch a rule off through the CSSOM instead,document.styleSheets[0].insertRule("body::before{display:none!important}", 0). - axe reports every text node as
incompletefor contrast while the grain (body::before, a pseudo-element over the page) is on:Element's background color could not be determined due to a pseudo element. With the grain off through the CSSOM, 418 text nodes per scheme were measured on nine pages at 1440 px: the lowest ratio is 5.22 in the light scheme (codein a callout on the paper) and 5.94 in the dark scheme. The grain (multiply at opacity 0.5 in light, screen at 0.16 in dark) lowers the real ratio by a few percent and was not measured. The only nodes leftincompleteare the links of the closed menu (details), not read open. - axe findings and their fixes:
heading-orderon Verify (the five chain prints areh3under the pageh1: a visually hiddenh2, classvh);scrollable-region-focusableon everypreat 390 px (tabindex="0"); contrast of the home stamp, 2.22 in the light scheme and 1.84 in the dark, because axe takes the logo plate, which is a mask, as its background (the stamp has a paper background now). Re-run after the fixes: no violation in either scheme at 390 and 798 px on six pages and at 1440 px in the dark scheme; light at 1440 px was run before the fixes and showed onlyheading-order. 1920 px, layout shift (layout-shiftentries), the open menu at 390 px and the nine pages by eye at 390, 798 and 1920 px were not read. - Network, home page, one load at 1440 px in the tool's browser: the site's own origin only, no cookie, empty local and session storage; one more request came from a Chrome extension of that browser (
chrome-extension://…/page-script.js), which shows as originnull. The capture of W-4 and V-3 needs a clean profile. - Weight of the build (
check-build.mjs): nine pages, 32 files, 194 internal links, no dead link and no missing fragment; css 18.2 KB, three woff2 files 116.2 KB (Roboto Flex 34 KB, Noto Serif 37 KB, Noto Serif italic 48 KB), the largest page 22.1 KB, the largest first load 218 KB (page plus the assets it names, not the files that css names). The budget is insite/org/budget.json. - Astro 5.18.2 builds and passes on Node 20.19.2 with npm 9.2.0 although
npm installwarnsEBADENGINE: Astro wants npm 9.6.5 or later, andunifont(Astro's fonts feature, unused) pullsundici8, which wants Node 22.19. Astro 6 and 7 need Node 22.12 and 22.23 (read withnpm view). A route folder named.well-knownundersrc/pagesis built as a route. A bare package path in css (url("@fontsource-variable/…/files/….woff2")) is resolved by Vite and hashed into_astro/. - Playwright through the tool: one call of 72 page loads with 36 axe runs did not return. Runs of nine pages for one scheme and one width finish. After that interruption
page.screenshottimed out at every call, also with a 60 s limit; headless Chromium from the shell worked:chromium --headless --no-sandbox --disable-gpu --hide-scrollbars --window-size=1440,2900 --screenshot=OUT URL, and--force-dark-modegivesprefers-color-scheme: darkthere while--blink-settings=preferredColorScheme=1stays light. Listeners of an interrupted run stay attached to the tool's page and fill the console log with their own errors: callpage.removeAllListeners()first.
6The npm packages in the SBOM (2026-11-18)
The SBOM build (tools/sbom/build-sbom.py, gate W-7) lists every registry package of site/package-lock.json as a component with its licence, its SHA-512 integrity and the OSV advisories, and writes site/NOTICE from the same list (--site-notice). tools/sbom/fetch-npm-evidence.py reads the registry and OSV; the answers are in sbom/evidence/npm.json and sbom/evidence/osv-npm.json.
- 380 registry packages were read; every integrity of the registry equals the one of the lockfile. The two workspaces of
site/are not registry packages. zod-to-ts1.2.0 states no licence in the registry. The installed package ships aLICENSEfile with the MIT text andCopyright (c) 2021 Sachin Raja(SHA-256901eb546213d344758178277346c83df776b3566895c507a82ee36447c6662ba, read on 2026-11-18); the SBOM takes MIT from it (npm_licencesintools/sbom/inputs.json).- Fourteen packages are outside the allowed licence terms: ten
@img/sharp-libvips-*(LGPL-3.0-or-later) and four@img/sharp-*platform packages (Apache-2.0 with LGPL-3.0-or-later, one also MIT). They are the native image libraries ofsharp; the lockfile marks them optional,astro.config.mjssetspassthroughImageService()so the site optimises no image, and the output holds none of them. The build prints each as a note and does not fail on it. - OSV listed 19 advisories on 2026-11-18 for six locked versions (20 entries in the SBOM, because one advisory names two
picomatchversions, 2.3.2 and 4.0.7): Astro 5.18.2 (13),sharp0.34.5 (3),esbuild0.27.7 (1) andzod3.25.76 (1). The 13 of Astro are fixed only in Astro 6 and 7, which need Node 22 (ADR-253). The next section assesses each of them; the SBOM still shows each asin_triage, with the assessment as its detail, as it does for the Rust advisories.
7Assessment of the OSV advisories of the npm packages (2026-11-18)
Each of the 19 advisories of the section above was read against what site/ uses. The evidence is a search of every .astro, .mjs, .js and .css file of site/ and the file astro.config.mjs: no define:vars, no transition: directive and no ClientRouter, no client: directive, no spread {...}, no named slot (three default <slot />), no dynamic tag name, no astro:assets, no Astro.request, no content collection or MDX; @astrojs/node, @astrojs/mdx and @astrojs/react are not in the lockfile; set:html appears twice, on strings written in the repository (faq.astro, areas.mjs). The output is static, has no adapter and no base, and Vercel serves the files. Everything the build reads is a file of the repository or of the snapshot. This is a reading of the use of each feature, not an audit of the Astro code.
- 1
GHSA-26w7-cxv4-gfx2
- Package
- astro
- Why it does not apply
- AVIF image optimisation:
passthroughImageService()is set, there is noastro:assets, andsharpis never loaded.
- 2
GHSA-2pvr-wf23-7pc7
- Package
- astro
- Why it does not apply
- The prerendered error page of a running server: the output is static and has no adapter.
- 3
GHSA-376h-93r7-7g6f
- Package
- astro
- Why it does not apply
- Stripping the configured
basein a running server: nobaseis set and no server runs.
- 4
GHSA-4g3v-8h47-v7g6
- Package
- astro
- Why it does not apply
- View Transitions: no
ClientRouterand notransition:directive.
- 5
GHSA-7pw4-f3q4-r2p2
- Package
- astro
- Why it does not apply
transition:*on hydrated islands: noclient:directive and no UI framework.
- 6
GHSA-8hv8-536x-4wqp
- Package
- astro
- Why it does not apply
- A named slot: only default slots are used.
- 7
GHSA-98hj-9722-w3j8
- Package
- astro
- Why it does not apply
- JSX and MDX rendering: neither integration is installed.
- 8
GHSA-f48w-9m4c-m7f5
- Package
- astro
- Why it does not apply
- Spread attribute names: no spread props.
- 9
GHSA-jrpj-wcv7-9fh9
- Package
- astro
- Why it does not apply
- Spread attribute names: no spread props.
- 10
GHSA-j687-52p2-xcff
- Package
- astro
- Why it does not apply
define:vars: not used.
- 11
GHSA-mh32-jxcr-mh9f
- Package
- astro
- Why it does not apply
- Dynamic tag names: none.
- 12
GHSA-r3h5-4585-7x3w
- Package
- astro
- Why it does not apply
- The image endpoint of
@astrojs/node: the adapter is not installed.
- 13
GHSA-xr5h-phrj-8vxv
- Package
- astro
- Why it does not apply
- Server islands: the output is static and has none.
- 14
GHSA-g7r4-m6w7-qqqr
- Package
- esbuild
- Why it does not apply
- The development server on Windows: no development server runs (
astro buildandserve.mjs) and the workstation runs Linux.
- 15
GHSA-fc5q-39xc-vjpf
- Package
- picomatch 2.3.2 and 4.0.7
- Why it does not apply
- A slow match of crafted extglob patterns: the patterns come from the configuration of the tools and never from input; no fixed version is listed; the worst case is a slow build.
- 16
GHSA-f88m-g3jw-g9cj
- Package
- sharp
- Why it does not apply
- libvips:
sharpis an optional dependency that the build never loads, and the site processes no image.
- 17
GHSA-rgj7-g3m4-5g8c
- Package
- sharp
- Why it does not apply
- libheif: the same.
- 18
GHSA-wq5f-xc86-pv6w
- Package
- sharp
- Why it does not apply
- librsvg: the same.
- 19
GHSA-mrhx-c7xc-m3w5
- Package
- zod
- Why it does not apply
- Memory use when validating oversized collections:
zodvalidates the configuration of Astro and the files of the site, and receives no external input.
The assessment is reopened by any use of a listed feature, by an adapter, a base or an image service, by an upgrade of Astro, or by a new advisory.
8Geometry, layout shift and requests of the nine pages (2026-11-18)
Measured on the served build (site/org/scripts/serve.mjs, built with SBOM_DIR set because this repository has no sbom/) in the browser pane of the Claude desktop app. Each of the nine pages (the eight and the 404 page) was loaded in a same-origin iframe of 390, 798 and 1920 px, 27 loads, and measured after load:
scrollWidthequals the inner width and no element lies past the right edge (preblocks scroll by design): no overflow in any of the 27.- Layout shift is 0.0000 within 700 ms of load in all 27.
- No link, button or
summaryoutside running text is smaller than 24 px in either direction. - The resource entries of the page name only the site's own origin; the page has no cookie and empty local and session storage.
- The open menu at 390 px (dark scheme) lists five links and stays inside the viewport (a screenshot, read by eye).
An iframe proves layout, not looks: the nine pages were not read by eye at the three widths, the light scheme was not read again, and the browser pane is not a clean profile, so the capture of W-4 and V-3 is still open. The Playwright tool did not return a call of 27 loads with a page.on("request") listener and was stopped at the owner's word; the pane's JavaScript tool did the same work.
10The quality checks of the build with eleven pages (2026-11-18)
Run on the build of site/ made with SBOM_DIR=<the docs repository>/sbom, served by serve.mjs --axe on port 8124 and driven by the Playwright tool of the desktop app (not a clean profile).
npm ci --ignore-scriptsadded 285 packages, with theEBADENGINEwarnings of the section above.npm run buildbuilt 11 pages in 1.56 s andcheck-build.mjsprintedpages 11, files 34, links checked 307,weight: css 19.8 KB, fonts 116.2 KB, largest html what-it-does.html 24.2 KB, largest first load what-it-does.html 221.8 KBandcheck-build: OK. The 307 links are the internal ones; no external link is checked.- axe 4.10.3 at 1280 px, default scheme, grain on: no violation on the ten pages and the 404 page.
color-contraststayedincompleteon all eleven (31 to 103 nodes) for the reason given above (the grain pseudo element). A computation of the contrast ratio of every text element against its first opaque ancestor background (limit 3 for large text, 4.5 for the rest) found no element below its limit on the ten pages in both schemes at 1280 px; like the measurement of 2026-11-17 it ignores the grain. - Overflow at 320, 375, 768, 1024, 1280 and 1920 px on the 11 pages (66 loads in one call of the Playwright tool, which returned):
scrollWidthexceededclientWidthonly at 320 px on every page (320 against 305, the page area next to a 15 px classic scrollbar). The cause wasmin-width: 320pxonbodyinsite/shared/src/styles/layout.css; the rule is removed. After the rebuild (same counts and weights,check-build: OK)scrollWidthequalsclientWidthat 280, 320 and 375 px on all 11 pages (265, 305, 360). Someielements have their right edge past the viewport (310 to 427 px) on/at all three widths and on/verifyat 280 and 320 px;bodyhasoverflow-x: hidden, so they cannot scroll, and they were not identified or looked at. - Requests: 684 in the run, all to
localhost:8124exceptchrome-extension://…/page-script.jsof the tool's browser; no cookie and noSet-Cookie. The local server sentstrict-transport-security: max-age=63072000; includeSubDomains,content-security-policy: default-src 'self',referrer-policy: no-referrer,x-content-type-options: nosniff, an emptypermissions-policyandcross-origin-opener-policy: same-origin. The 404 page answers 404 and logs one console error for that status. - A search of
site/org/distfor a home-directory path (Linux or macOS),sourceMappingURL,.verceland.envfound nothing. - Screenshots at the six widths were taken for Home, What it does and Privacy; only Home at 320 px was opened, at a size too small to read. No page was read by eye at any width in this run.
11Headers, structured data and the Vercel deployment (2026-11-18)
- Vercel does not serve a header whose value is empty:
vercel.jsonsetPermissions-Policyto""and the live response (curl -I https://oblivios-docs.vercel.app/) had no such header, while the localserve.mjssent it. Vercel addsaccess-control-allow-origin: *to the static files; no key ofvercel.jsonremoves it. Content-Security-Policy: default-src 'self'does not coverbase-uri,form-actionorframe-ancestors; each is a directive of its own.frame-ancestors 'self'keeps the iframe measurement of the section above working (the pages frame each other on one origin);'none'would stop it.- Chromium reports
Unrecognized feature: 'bluetooth'for aPermissions-Policythat lists it; the other fourteen names of the header invercel.jsonraised no message. - A JSON-LD block is a
<script type="application/ld+json">that runs nothing and thatscript-srcanddefault-srcdo not apply to;check-build.mjsremoves exactly that tag before it looks for any other<script>. In Astro the tag needsis:inlineandset:html, and every<in the JSON is written<so that the data cannot close the tag. - After
VERCEL=1 npm run buildthe localdist/holds the analytics tag, and the local server answers its path with the 404 page: the pane then logsRefused to execute script ... MIME type ('text/html')on every load. Rebuild without the variable before a local read of the console. - On the live site on 2026-11-18 (11 pages at 390, 798 and 1920 px in the pane, 33 loads): no overflow, no other origin, no cookie, empty local and session storage; the only failing request was
/_vercel/insights/script.js(404): the Analytics switch was not on at that deployment. - After the push of ADR-262 and the owner's Enable of Web Analytics (read 2026-11-18,
curl -Iand the browser pane): the new headers were live about 40 s after the push;/_vercel/insights/script.jsanswers 200application/javascript; one load of/what-it-doesin the pane made the requests of the page plusGET /_vercel/insights/script.jsandPOST /_vercel/insights/view, both 200 and both on the site's own origin; the only origin of the page's resources is the site itself,document.cookieis empty and local and session storage are empty. Every page but the 404 page has one JSON-LD block and the robots meta of ADR-262. The classic script path of ADR-261 is therefore confirmed. The pane's console log is cumulative across navigations: thebluetoothwarning in it came from an earlier local load, the live header does not list it.
12Domain, DNS and certificate of oblivios.org (2026-11-18)
Read after the owner linked oblivios.org to the Vercel project (the domain list of the project showed oblivios.org as production, valid, and www.oblivios.org and the Vercel address as 308 redirects to it).
digagainst a public validating resolver: the apex has one A record (a Vercel address) and no AAAA;wwwis a CNAME to a target that Vercel assigns to the project; the name servers of both domains are the three of the registrar; no CAA, TXT or MX record on either domain. A DS record is at the registry for both domains, and the answer foroblivios.orgcarries theadflag, so the signed zone validates.oblivios.devhas a DS record, no A, AAAA or CNAME record and answersNOERRORwith no data: no site and no deployment yet.- With the address resolved by hand (
curl --resolve oblivios.org:443:<address>):https://oblivios.org/answers 200 over HTTP/2 with a verified certificate (Let's Encrypt, subjectoblivios.org, valid 2026-11-18 to 2027-02-16);https://www.oblivios.org/andhttp://oblivios.org/answer308tohttps://oblivios.org/;https://oblivios-docs.vercel.app/what-it-doesanswers308tohttps://oblivios.org/what-it-does. The headers, the ten sitemap addresses (each 200), the canonical URLs,robots.txt,security.txt, the key file, the social preview and the analytics script answer as they did on the Vercel address;/nopeanswers 404. - The workstation's resolver returned no address for
oblivios.org(getent hostsempty,curlwithout--resolvegave status 000) and the browser pane's navigation to it failed, whiledigagainst a public resolver answered. The cause is the DNS cache of the home router, which the workstation uses: it held an empty answer for the apex and forwww, cached for the negative time of the zone's SOA record (3600 s), and its answer showed the remaining time (2517 s at 14:49, counting down), while the authoritative server and three public resolvers returned the address. The owner, on the same network, could not open the site either, while Google reached it and accepted the sitemap. Ways out: wait for the entry to expire, clear or restart the router's cache, or use a public resolver or the browser's secure DNS; reads of the live domain use--resolvemeanwhile. - The site is public while the four repositories are private: each of the ten pages links to them (4 to 8 links per page) and
curlwithout a login got 404 from all fourgithub.com/Beau4201/...addresses on 2026-11-18. R-7 of the launch design puts the sites after the flip of the repositories. The four repositories were made public later the same day (ADR-265), so the links now resolve.
13Flip, builder tests and live read (2026-11-18)
gh2.46 has no--accept-visibility-change-consequencesongh repo edit(unknown flag); the flip isgh api -X PATCH repos/Beau4201/<repository> -f visibility=public, read back withgh api repos/Beau4201/<repository> --jq .visibilityand with an anonymousgit clone(default branch only).- A scratch clone of the private repository for a test of the builder needs
git clone --local --no-hardlinkswhen the scratch folder is on another device (hard links across devices fail). The clone holds only committed state, so a change to the builder must be committed before a sabotage run against the clone sees it. - The sabotage run plants eight leaks in a clone, commits them there and runs
python3 -I tools/docs/build-public-docs.py <out>against a non-empty output folder; the build must exit non-zero, name every leak and leave the output folder byte for byte as it was (ADR-266 gives the eight). - The live read of the public site takes its page list from
robots.txt(theSitemap:line, then the sitemap or a sitemap index), reads status,Set-Cookie, resources of another origin, forms, scripts, language, title, level-one headings and images without text per page, the security headers of the home page, every internal link withHEADand every external link; a script of about 100 lines withurllibdoes it, nothing outside the standard library. - Not run (ADR-267): an automated accessibility check and a phone viewport on the live site, a browser capture of the pages other than the home page, the Speed Insights and preview settings of the host.
14Pre-flip scans of the four repositories (2026-11-18)
Run with python3 tools/docs/preflip-scan.py --dist site/org/dist <folder of the repositories> (launch design S-1 to S-3) on the head of the default branch of each repository: platform 1f42fcb, manifest 9d8ef6f, services 70f6fd0 and the docs snapshot at that time. The tool exits 1 on a leak, a private key, the owner's account or domain, or a pattern inside a binary or an archive; it exited 0. python3 tools/docs/preflip-scan.py --self-test checks its parsers.
- S-1: gitleaks 8.16.0 (the Debian package
8.16.0-1+b12;gitleaks versionprints onlyversion is set by build process; the release is from 2023, so its rules are older than the current ones) reported no leak in the 30, 590, 38 and 171 commits it scanned in docs, platform, manifest and services.git rev-list --countgives 30, 594, 38 and 173: gitleaks scanned four and two commits fewer in platform and services, and the cause (merge commits) was not checked. Only the default branch is scanned; the local branches of platform and services stay private (R-2) and were not scanned. - S-2, text files (docs 98, platform 994, manifest 16, services 182): the findings that name a place are 19 paths into the
srvtree of the build server in platform and 17 in services, 16 mentions of the script directory of the build host in platform and 1 in manifest, and 1 home-relative script path in manifest (services has one home-relative string in a test). The paths are the defaults of environment variables (AOSP_TREE,EXIT_WORK,VAULT_WORK,PWM_WORK) in tool scripts and the description of where the build server keeps its trees; the script directory is the directory of the foundation repository that theSOURCE.mdrecords name. No host name, user name, key or private address is in them. The owner decided on 2026-11-18 to remove them (ADR-263): the scripts now requireAOSP_TREE,EXIT_WORK,VAULT_WORK,PWM_WORK,EXIT_APP_SCRATCHandDNSRESOLVER_SCRATCH(${VAR:?set VAR}) instead of defaulting to a path, so a run on the build server needs them exported first, and the prose names<build-root>,tools/build/and<home>/as the docs snapshot does; the history keeps the old text (R-6). Every other number is a documentation or reserved range, a test value, an icon table, a coordinate in an SVG, or upstream code (theonionmasqsources name three public addresses). The e-mail addresses are the owner's contact inSECURITY.mdand in the author line of 48 patch files, upstream authors in licence files, and example addresses in tests. - S-2, binaries and archives: the 273 binary files (265 in platform, 7 in docs, 1 in services) hold no home path, server path, owner account or key; neither does any entry of the two jar files (
airpods-core.jar40 entries,gradle-wrapper.jar34 entries; the scan opens an archive because a compressed entry hides its strings). The built output ofoblivios.orgholds only the contact address, as designed. - Git identity: every commit of the four default branches (30, 594, 38 and 173) has author and committer
beau4201with the Gmail address that is also the public security contact. At the flip the history carries that address for ever (ADR-243 to ADR-245 accepted the exposure of history; the address in the author lines was not named there). - S-3: nine PNG, fifty SVG, one ICO and 257 WebP files were read from their structure (
exiftoolis not installed, so the tool parses PNG chunks, WebP chunks, JPEG APP1 and SVG markup itself). The WebP flags carry no EXIF, XMP or colour-profile chunk. Five PNG files of the site (the Apple touch icon,favicon-32,icon-192,icon-512,icon-maskable-512) carrydate:create,date:modifyanddate:timestamptext chunks and atIMEchunk from 2026-11-17 15:28 UTC, written by ImageMagick; they hold no author, software or path. The owner chose to remove them on 2026-11-18 (ADR-263): the text and time chunks were dropped and nothing else was touched, which the pixel signature of ImageMagick (identify -format %#) confirms equal for each file.social-preview.pngand the AirPods icons carry none.site/shared/public/brand/oblivios-logo.svgholds a<metadata>element with a C2PA manifest (content credentials). Decoded, its claim saysClaude provided this file at the request of a user and may have created or modified the file contents, with the generatorClaudeand the labelAnthropic Files, anorigin-confidenceofunknown, and ac2pa.openedaction on an ingredient of typeimage/svg+xml; it names no logo generator, and the owner confirmed on 2026-11-18 that Claude made the logo. The file is served athttps://oblivios.org/brand/oblivios-logo.svgwith that manifest; it is kept, as it states the origin correctly (ADR-263). identify -verboseof ImageMagick listsdate:create,date:modifyanddate:timestampfor every file: they are the times of the temporary copy it reads, not metadata of the image.- R-3, read with
gh api(all four repositories are private): no description and no topic; the homepage is empty except in docs, where it is the earlier Vercel address; the wiki and the projects are on; the endpoints of private vulnerability reporting and of Dependabot alerts answer 404 andsecurity_and_analysisis null; the default branch is not protected. That these features are not offered for a private repository on this plan is[assumption: not checked against GitHub's documentation].
15The Astro build of oblivios.dev (2026-11-19)
Decision and scope: ADR-268. The application is site/dev in the workspace of site/, with no package added to the lockfile (the entry for the workspace and its link are the only change).
- Build and serve:
SBOM_DIR=<path of the sbom directory> npm run build -w devfromsite/(the private repository has nosbom/), thennpm run serve -w dev -- --port 8125.[measured]the build takes about 3 s: 289 pages (267 decisions, 14 list pages, search, the five pages of the bill of materials, home and the 404 page), 7,676 links checked, CSS 33.7 KB, fonts 116.2 KB, script 25.1 KB, largest HTMLadvisories.html26.8 KB, largest first load 263 KB. - The decision log has 267 entries, one per line. Eight have a number of columns other than seven: ADR-028, ADR-030 and ADR-087 have eight, ADR-125, ADR-126 and ADR-127 five, ADR-165 and ADR-254 six (a cell holds the separator of the table, or a column is missing). The reader shows them as written and the page says so. The title of an entry is its first sentence, cut at its first clause (a colon, a dash, a bracket,
, as) when longer than 115 characters; 68 of the 267 titles are still over 130 characters. AnADR-nnnin a cell is a link when the entry exists; a Markdown link in the log is relative todocs/governance/and becomes a file on GitHub. - The search index (
src/lib/search-index.mjs): 2,914 documents (267 decisions, 971 libraries, 45 upstream projects and modules, 6 tools, 27 advisories, 31 data sets and sources, 1,567 files), 11,214 words, 87,500 postings, 1.5 MB raw and about 460 KB gzipped[measured: node over the build]. A first version stored the length of a document underl, the key that a component uses for its licence: a data hit showed18where its licence belonged, and the filter on a licence matched nothing. The length isw. - Ranking
[measured: 23 queries in the browser pane]: the expected entry was in the first three for 21 before the fixes, and a search took 1 to 5 ms. The two misses wereastro 5.18(the advisories, which repeat the name in three fields, came before the library) andmit(875 hits, because a typed word of three letters was stretched tomitigation). The fixes: a component or data set whose name is typed whole is lifted, a three-letter word that exists is not stretched into its continuations, and a document that lacks a word is shown only when no document has them all (the first version showed them as soon as fewer than eight had all words, soGHSA-26w7listed twenty advisories). The set was not run again after the fixes. - The pages use the class names of
site/org/src/styles/pages.css, and a rule applies by name:.bar(the status bars ofoblivios.org) turned a filter bar into a grid of 190 px,.cl(the cloud print) widened a list,.factsstacked the lead of the home page. The portal's own names aretbar,cmplanddfacts, and the portal copies only the patterns it uses intosite/dev/src/styles/pages.css. - Overflow
[measured]: fifteen pages at 320, 390, 600, 798, 1024 and 1440 px overflowed only on/adr/87at 320 and 390 px. A sweep of all 267 decision pages at 320 px then found 58 pages wider than the screen: a long word (a path in a title) kept the header band wide, and a grid track ofminmax(0, 720px)grows to 720 px for a long word instead of shrinking. Afteroverflow-wrap: anywhereon the header band and the facts, three pages (ADR-150, ADR-211, ADR-235) were left, caused by the track; it isminmax(0, 1fr)with a maximum width now. The sweep after that change was interrupted, so the 267 pages are not read as clean. Sweeps of that size run as one width per call (owner-working-rules.md). - Closing animation
[measured: the height of the element in every frame]: with the transition in the rule of the closed state andtransition: nonein the rule of[open], a list of 13 advisories is 1,676 px high from the first frame after the click, and on closing is 386 px after 100 ms and 52 px after 250 ms; the filter panel is 490 px at once and 387 px in the second frame of closing. A real click gives the same as a script.::details-contentis in Chromium; other browsers open and close without a transition. - A local server that sends no
Cache-Controllet the browser keep the stylesheet of the earlier version, so an animation that was already removed was still seen: serve withCache-Control: no-store(dev/scripts/serve.mjsdoes) and give a stylesheet a version in its address while it is a scratch page. - The shared changes (
Header.astro,Base.astro,areas.mjsofoblivios.org) were checked by buildingoblivios.orgfrom the stashed tree and from the changed tree and comparing the HTML: only</picture> </a>differs, one extra space, no change in what is drawn. check-build.mjsof the portal differs from that ofoblivios.orgin four places: it requires exactly one script,<script defer src="/browse.js">, on every page; it reads that file and fails on storage, a cookie, another network API, dynamic code, a module import and anyfetchbut/search-index.json; it checks the index (shape, sorted words, size under 2.2 MB, at least one document per decision); and it does not apply the placeholder-text rule to decision pages, which show the record as written (eleven entries useplaceholderorTODOfor what they describe). The count of decision pages must equal the number of rows of the log.- A
pkill -fwith the pattern of the server in its own command line killed the tool shell again (exit 144); a server is stopped by its exact PID. - Overflow sweep finished and axe run (2026-11-19, the build of 290 pages
[measured: scripted iframes in the browser pane, one width per call]). At 320 px the sweep of all 289 pages of the sitemap first found the same three pages as before (ADR-150, ADR-211, ADR-235; 358, 1,264 and 2,423 px wide), so the earlier fix had not been the cause. Causes, found withgetBoundingClientRectover the descendants of the page:.prosehasmargin: auto, which makes a grid item shrink to its content instead of filling its track; an inlinecode(a path) and the.evstamp arewhite-space: nowrap. The portal now sets the side margins of.adr .proseto 0 and lets.adr .prose code,.dfacts codeand.adr .evwrap (overflow-wrap: anywhere); aprekeeps scrolling. After that, 0 of 289 pages are wider than 320 px. axe-core 4.10.3 (serve.mjs --axe) on 12 pages (home, decisions pages 1 and 2, search, the five pages of the bill of materials, ADR-268, ADR-211, the 404) found, in the dark scheme at 375 px, threeheading-order(ah3before anyh2: the decision list, the chart on Components, theShown as writtennote) and onescrollable-region-focusable(thepreon Verify). The three headings keep theirh3styling and carryaria-level2 (Entry.astrotakes alevel), theprehastabindex="0". After that: 0 violations in the dark scheme at 375 and 1440 px and in the light scheme at 375 and 1024 px, with the colour-contrast rule on. Not run: dark at 1024, light at 1440, the pages beyond those 12 (the other 266 decision pages share the layout of ADR-268 and ADR-211), a keyboard pass, and a screen reader. - Search read again after the ranking fixes (2026-11-19)
[measured: 24 queries through /search?q= in the browser pane, the top three read by eye, 1 to 4 ms each]:ADR-208,208,GHSA-26w7,astro 5.18,vault-core,OFL-1.1,boot animation,freeholdos rename,vercel analytics,ota server,airpods,lynx,stallionandgrapheneos baselineput the expected record first or among the first three; a typo of one letter in Compartments and one in Seedvault still find Compartments and the Seedvault entries; a word with no meaning finds nothing and says so;compartments exitputs the data setCompartments exit mask listbefore the decisions. Weak before a change the same day:mitreturned the 424 libraries whose licence is MIT with a long licence expression first (aws-lc-sys), andduress unlockranked the amendment ADR-210 above the base entry ADR-145. Two rules were added tobrowse.js(a library whose whole licence is the single typed word gets +5; a decision whose title starts withAmendis multiplied by 0.8); the 27 queries read again gave the same results except thatmitnow starts withamplify,bail,bincode(licence exactly MIT) andduress unlockgives ADR-147, ADR-145, ADR-233, so the base entry is second and not first.apache-2.0is three tokens and does not get the licence rule. a typo of signing finds entries that mention signing but not clearly the best ones; no tuning, because there is no defined best answer for a typo. Not tested: Firefox and Safari, the search on a phone by hand, the keyboard (arrow keys, focus), a screen reader. The first test set of 23 queries was not written down, so the two sets are not comparable. - Documents as pages (2026-11-19, ADR-269)
[measured]. The ten published documents are read bydocuments.mjs; the first run failed on two things that only the real files showed: a row of the threat model that had two table rows on one line, joined by a literal backslash and n (fixed in the source), and a table indented inside a list item in the Duress Unlock notes (the reader now takes an indented table or paragraph after a blank line as part of the item). A pipe inside a code span is text, not a cell separator. - The
.fnlink took the gradient of the link rule as a solid fill because the shared rule that turns the gradient into an underline names.prose a,.callout a,.faq aand.kv aand not.fn a: a new rule for an element of the portal is checked against the shared selector list. - The browser pane cannot take a screenshot while it is hidden (
Screenshot timed out after 5s);show_panedid not change that for this session. Pages were rendered withchromium --headless --no-sandbox --window-size=W,H --virtual-time-budget=4000 --screenshot=<png> <url>and read as images, while the JavaScript tool still measured and ran axe in the hidden pane. - The snapshot builder copies the files of
site/that git tracks: a new file that is not committed is missing from the snapshot, and the build of the snapshot then fails on an import. The check is to commit, build the snapshot into a copy ofoblivios-docs(cp -afirst, because the two linkssbom/README.mdandtools/LICENSEresolve only where those files already are), linksite/node_modulesinto the copy and runnpm run build -w devthere: 305 pages and 10,898 links, the same as in the private repository. The copy was not pushed andoblivios-docswas not changed. - A word in a document is a word of the index. After the notes named three misspelled test queries, the search for each of them found the notes and nothing else, and
astro 5.18stopped finding the library: the tokenizer splits5.18into5.18and18, the notes made5.18an exact word, and a word that exists was no longer taken as the start of5.18.2. A word with a dot is now always also the start of longer words, and the notes do not spell a test typo. - Header and tabs (2026-11-19, ADR-270)
[measured]. Six links, the tag and the button did not fit in the 1,160 px container: the flex row shrank the links to their longest word andThreat modelwrapped, at every width up to 1,630 px, although the pane at 800 px showed the drawer;white-space: nowrapwith a smaller gap and two breakpoints (tag, then button) fixed it, read asgetClientRects().lengthof every link at ten widths (a link taller than 24 px is not a wrapped link: it has 8 px of padding). The tabs got the colour of the band with.ph:has(+ .subnav)and a smaller bottom padding of the band. - The chips of the search page showed 0 until a word was typed, because the counts were written only by a search. The page now writes the number of documents of each kind into the chip at build time (
data-total, from the same lists that make the index, including the 214 documents of the published files), andbrowse.jsputs those numbers back when the field is empty or cleared. A count that the build can know is not left to the script. - The scanner of the snapshot builder reads a hex letter followed by two colons as the start of an IPv6 address: a stylesheet rule that put the scrollbar pseudo-element after the class
c, and a comment that quoted it, both failed the audit of the snapshot with the findingaddress, while.advd::details-contentpassed. The rule is written withdiv, and a comment does not spell the pattern. -webkit-line-clampon a box with padding shows the start of the third line under the second; the clamp belongs on an inner span. A contents column that is a grid of a number and a span keeps the numbers aligned when a title takes two lines.scroll-behavior: smoothis set on the page:scrollIntoView()andscrollBy()in a measuring script then scroll over time (and not at all while the pane is hidden), so a script that positions the page usesscrollTo({ top, behavior: "instant" }). ArequestAnimationFrameloop does not run while the pane is hidden: the section marker of the contents column and every frame log need the pane shown (show_pane), and the log of a click must be installed before the click.- Disclosure, measured with real clicks (the
computerclick of the pane, with a listener that loggeddocument.getAnimations()and the height in every frame). The owner wanted the opening to move and the page had been made to open at once, on a misreading of an earlier remark (ADR-268, corrected in ADR-271). Thetransitionthat counts is the one of the state the element goes to, so the rule of[open]carries the opening and the rule of the closed state the closing, andcontent-visibilitywithallow-discreteis in both so that the content stays drawn;[open] ... { transition: none }, which an earlier version had, removed the opening motion. Measured after the change:Read the 13 advisoriesgrows from 46 to 2,415 px in about 300 ms, slowing towards the end (486, 1,236, 1,755, 2,062, 2,230, 2,322, 2,371, 2,397, 2,409 px at 33 ms steps) while the plus turns, and closes in about 270 ms; the filter panel at 725 px goes from 46 to 479 px in about 340 ms and back in about 260 ms.getAnimations()lists the plus and the colour of the button but not the height of::details-content, so the height read in every frame is the evidence for it. - A screenshot of the pane failed with a timeout while it was hidden and worked when it was shown;
show_panemade it visible for some minutes only. The pane then was 725 px wide, so a phone layout, which is the size to read mobile pages at.
16Counts on the pages
Decision statuses are classified by the first word of the status cell: Accepted…, Proposed…, anything else. On 2026-11-17 the published log had 249 rows (163 accepted, 60 proposed, 26 other) and this repository 250. The grouping of decisions per part of the system is a list in gen.py; a decision that belongs to two parts (ADR-186 to ADR-188) is counted in both.
Read from docs/architecture/site-engineering-notes.md.