ObliviOS Developer portal Project site

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 a file:// 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 as data: 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 with preview_start and its url argument. A first navigate to the 127.0.0.1 address was denied; preview_start with the same url opened it, and navigate worked afterwards in that tab. Kill the server at the end of the session (the process list shows python3 -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 ?norv to 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.scrollWidth against innerWidth, and the elements whose getBoundingClientRect().right exceeds innerWidth (ignore the hidden defs svg, the review layer and pre blocks, 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 href that is not external must name a generated page, and a #fragment must be an id on 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 (feTurbulence plus feDisplacementMap for a warped edge, a second turbulence thresholded by feColorMatrix and feComposite for 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 with multiply. 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 svg and placed with <use>. A cloned element takes its inheritable properties from the use element, and a CSS selector that depends on an ancestor of the use (.alt .pp) does not match the clone. The hole colour of the details is therefore var(--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 a viewBox of x 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 p outranks a plain class on a paragraph; a styled paragraph inside prose needs .prose p.<class>.
  • details::details-content with interpolate-size: allow-keywords animates the FAQ in Chromium; other engines open the answer at once, which is the fallback.
  • A bar of accepted against proposed decisions is a div with two widths and a text equivalent in an aria-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>, a style attribute and a data: URI are blocked, and the mockups used all three. The build therefore sets build.inlineStylesheets: "never" and vite.build.assetsInlineLimit: 0, draws SVG widths as attributes (stroke-width="15", a bar is an svg of rect elements), keeps the grain, the stamp mask and the logo mask as files in site/shared/public/, and scripts/check-build.mjs fails on any of them in the output.
  • scripts/serve.mjs serves dist/ with the headers and cleanUrls of vercel.json; --axe serves axe-core at /__axe.js; --review leaves 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 when review.js or storage access is in a production output. The server must start in site/org (it reads dist and vercel.json from the working directory); npm --prefix <site> run serve -w org -- --port N does that. axe-core sits in site/node_modules (hoisted), not in site/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 incomplete for 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 (code in 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 left incomplete are the links of the closed menu (details), not read open.
  • axe findings and their fixes: heading-order on Verify (the five chain prints are h3 under the page h1: a visually hidden h2, class vh); scrollable-region-focusable on every pre at 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 only heading-order. 1920 px, layout shift (layout-shift entries), 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 origin null. 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 in site/org/budget.json.
  • Astro 5.18.2 builds and passes on Node 20.19.2 with npm 9.2.0 although npm install warns EBADENGINE: Astro wants npm 9.6.5 or later, and unifont (Astro's fonts feature, unused) pulls undici 8, which wants Node 22.19. Astro 6 and 7 need Node 22.12 and 22.23 (read with npm view). A route folder named .well-known under src/pages is 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.screenshot timed 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-mode gives prefers-color-scheme: dark there while --blink-settings=preferredColorScheme=1 stays light. Listeners of an interrupted run stay attached to the tool's page and fill the console log with their own errors: call page.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-ts 1.2.0 states no licence in the registry. The installed package ships a LICENSE file with the MIT text and Copyright (c) 2021 Sachin Raja (SHA-256 901eb546213d344758178277346c83df776b3566895c507a82ee36447c6662ba, read on 2026-11-18); the SBOM takes MIT from it (npm_licences in tools/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 of sharp; the lockfile marks them optional, astro.config.mjs sets passthroughImageService() 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 picomatch versions, 2.3.2 and 4.0.7): Astro 5.18.2 (13), sharp 0.34.5 (3), esbuild 0.27.7 (1) and zod 3.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 as in_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. 1

    GHSA-26w7-cxv4-gfx2

    Package
    astro
    Why it does not apply
    AVIF image optimisation: passthroughImageService() is set, there is no astro:assets, and sharp is never loaded.
  2. 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. 3

    GHSA-376h-93r7-7g6f

    Package
    astro
    Why it does not apply
    Stripping the configured base in a running server: no base is set and no server runs.
  4. 4

    GHSA-4g3v-8h47-v7g6

    Package
    astro
    Why it does not apply
    View Transitions: no ClientRouter and no transition: directive.
  5. 5

    GHSA-7pw4-f3q4-r2p2

    Package
    astro
    Why it does not apply
    transition:* on hydrated islands: no client: directive and no UI framework.
  6. 6

    GHSA-8hv8-536x-4wqp

    Package
    astro
    Why it does not apply
    A named slot: only default slots are used.
  7. 7

    GHSA-98hj-9722-w3j8

    Package
    astro
    Why it does not apply
    JSX and MDX rendering: neither integration is installed.
  8. 8

    GHSA-f48w-9m4c-m7f5

    Package
    astro
    Why it does not apply
    Spread attribute names: no spread props.
  9. 9

    GHSA-jrpj-wcv7-9fh9

    Package
    astro
    Why it does not apply
    Spread attribute names: no spread props.
  10. 10

    GHSA-j687-52p2-xcff

    Package
    astro
    Why it does not apply
    define:vars: not used.
  11. 11

    GHSA-mh32-jxcr-mh9f

    Package
    astro
    Why it does not apply
    Dynamic tag names: none.
  12. 12

    GHSA-r3h5-4585-7x3w

    Package
    astro
    Why it does not apply
    The image endpoint of @astrojs/node: the adapter is not installed.
  13. 13

    GHSA-xr5h-phrj-8vxv

    Package
    astro
    Why it does not apply
    Server islands: the output is static and has none.
  14. 14

    GHSA-g7r4-m6w7-qqqr

    Package
    esbuild
    Why it does not apply
    The development server on Windows: no development server runs (astro build and serve.mjs) and the workstation runs Linux.
  15. 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. 16

    GHSA-f88m-g3jw-g9cj

    Package
    sharp
    Why it does not apply
    libvips: sharp is an optional dependency that the build never loads, and the site processes no image.
  17. 17

    GHSA-rgj7-g3m4-5g8c

    Package
    sharp
    Why it does not apply
    libheif: the same.
  18. 18

    GHSA-wq5f-xc86-pv6w

    Package
    sharp
    Why it does not apply
    librsvg: the same.
  19. 19

    GHSA-mrhx-c7xc-m3w5

    Package
    zod
    Why it does not apply
    Memory use when validating oversized collections: zod validates 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:

  • scrollWidth equals the inner width and no element lies past the right edge (pre blocks 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 summary outside 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.

9The drawer menu, the checks and the regeneration (2026-11-18)

  • The menu is a native popover (<button popovertarget> and <div popover>): no script, Escape and a tap outside close it, and it sits in the top layer. A position: fixed child of the sticky header was not an option: the header has backdrop-filter, and a fixed child of such an element is positioned against it, not against the viewport.
  • The drawer slides over transform (340 ms in, 220 ms out, curve --ease-drawer, cubic-bezier(0.32, 0.72, 0, 1)) and the page dims over ::backdrop; both need transition: overlay ... allow-discrete, display ... allow-discrete and an @starting-style rule for the enter. Measured at 390 px in the browser pane: the drawer moves from outside the screen to 98 px from the left, 293 px wide (75 percent) and 844 px high, the backdrop reaches 0.5, and it is gone after 220 ms.
  • A rule .hd nav { ... } also matched the nav inside the drawer and hid it at 860 px and below; header rules are scoped to .hd .c > nav.
  • Layout of every page and width without resizing the pane: put the page in a same-origin iframe of that width from the JavaScript tool, and read scrollWidth, getBoundingClientRect and layout-shift entries inside it. This ran with the pane hidden, when a click and a screenshot failed (Screenshot timed out after 5s).
  • A state that needs a click is rendered from a copy of dist/ with the attribute set (<details open> for the earlier menu) and a static server on another port, with chromium --headless --no-sandbox --disable-gpu --hide-scrollbars --virtual-time-budget=3000 --window-size=W,H --screenshot=OUT URL; without the virtual time the screenshot caught the entry animation half done. --force-dark-mode gives the dark scheme.
  • A server started for a check is stopped with fuser -k PORT/tcp. pkill -f with a pattern that also stands in the command line of the same shell killed that shell (exit code 144).
  • The npm evidence is fetched with python3 tools/sbom/fetch-npm-evidence.py site tools/sbom/evidence (about 2 minutes; registry.npmjs.org and api.osv.dev, public names and versions only; it resumes from npm.json).
  • The site is built in this repository with SBOM_DIR=<the docs repository>/sbom, because this repository has no sbom/.
  • python3 tools/docs/sync-site.py "<what changed>" [--push] runs the whole chain below in one command (it needs the four schema files in <home>/.cache/oblivios/schemas or SCHEMA_DIR): the clean state of the five repositories, the snapshot, the SBOM with --check and sha256sum -c, VERCEL=1 npm run build of site/org and site/dev, the commit in oblivios-docs, with --push the push, then the live check: every file of both builds is fetched from oblivios.org and oblivios.dev and must be byte for byte the same (up to 480 s of waiting for Vercel), the headers of vercel.json must be on the home page and a missing page must answer 404; any difference or an unresolved domain exits non-zero. --verify-live runs only the check. Read on 2026-11-19 after the push of the portal snapshot: 33 files of oblivios.org identical, headers equal; oblivios.dev has no A or AAAA record and no Vercel project, so the check fails there until the owner connects the domain; a second regeneration of an unchanged state makes no commit. It does not push by itself: every push is asked for (CLAUDE.md).
  • The snapshot and the SBOM are regenerated in this order: python3 tools/docs/build-public-docs.py <docs repository> (it builds in a staging directory, audits every file and leaves the directory as it was on a finding, ADR-266); a clean copy of that directory without .git and .serena (the working directory of the docs repository gets .serena/ and .playwright-mcp/ files from tools, which would enter files.sha256); python3 tools/sbom/build-sbom.py --root <folder of the repositories> --docs <clean copy> --evidence tools/sbom/evidence --schemas <folder of the four schema files> <docs repository>/sbom, again with --check; then sha256sum -c oblivios-docs/sbom/files.sha256 in the folder of the repositories. The three code repositories must be clean and committed, or the build stops. The schema files are the ones named in sbom/README.md.
  • Vercel Web Analytics (ADR-261, Vercel documentation read on 2026-11-18): the plain HTML setup is one script tag and a project switch (Analytics, Enable), which adds the routes /_vercel/insights/* and /<unique-path>/* at the next deployment; the documentation names the script path /<unique-path>/script.js and this site uses the classic /_vercel/insights/script.js, which a first deployment has to confirm. The site adds the tag only when VERCEL=1, which Vercel sets in the build only when the project exposes its system environment variables (Environment Variables, Enable access to System Environment Variables); without that the build has no tag and the check does not notice. W-3 of the launch design says no environment variables: this one is the system's.

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-scripts added 285 packages, with the EBADENGINE warnings of the section above. npm run build built 11 pages in 1.56 s and check-build.mjs printed pages 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 KB and check-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-contrast stayed incomplete on 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): scrollWidth exceeded clientWidth only at 320 px on every page (320 against 305, the page area next to a 15 px classic scrollbar). The cause was min-width: 320px on body in site/shared/src/styles/layout.css; the rule is removed. After the rebuild (same counts and weights, check-build: OK) scrollWidth equals clientWidth at 280, 320 and 375 px on all 11 pages (265, 305, 360). Some i elements have their right edge past the viewport (310 to 427 px) on / at all three widths and on /verify at 280 and 320 px; body has overflow-x: hidden, so they cannot scroll, and they were not identified or looked at.
  • Requests: 684 in the run, all to localhost:8124 except chrome-extension://…/page-script.js of the tool's browser; no cookie and no Set-Cookie. The local server sent strict-transport-security: max-age=63072000; includeSubDomains, content-security-policy: default-src 'self', referrer-policy: no-referrer, x-content-type-options: nosniff, an empty permissions-policy and cross-origin-opener-policy: same-origin. The 404 page answers 404 and logs one console error for that status.
  • A search of site/org/dist for a home-directory path (Linux or macOS), sourceMappingURL, .vercel and .env found 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.json set Permissions-Policy to "" and the live response (curl -I https://oblivios-docs.vercel.app/) had no such header, while the local serve.mjs sent it. Vercel adds access-control-allow-origin: * to the static files; no key of vercel.json removes it.
  • Content-Security-Policy: default-src 'self' does not cover base-uri, form-action or frame-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 a Permissions-Policy that lists it; the other fourteen names of the header in vercel.json raised no message.
  • A JSON-LD block is a <script type="application/ld+json"> that runs nothing and that script-src and default-src do not apply to; check-build.mjs removes exactly that tag before it looks for any other <script>. In Astro the tag needs is:inline and set:html, and every < in the JSON is written < so that the data cannot close the tag.
  • After VERCEL=1 npm run build the local dist/ holds the analytics tag, and the local server answers its path with the 404 page: the pane then logs Refused 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 -I and the browser pane): the new headers were live about 40 s after the push; /_vercel/insights/script.js answers 200 application/javascript; one load of /what-it-does in the pane made the requests of the page plus GET /_vercel/insights/script.js and POST /_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.cookie is 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: the bluetooth warning 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).

  • dig against a public validating resolver: the apex has one A record (a Vercel address) and no AAAA; www is 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 for oblivios.org carries the ad flag, so the signed zone validates. oblivios.dev has a DS record, no A, AAAA or CNAME record and answers NOERROR with 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, subject oblivios.org, valid 2026-11-18 to 2027-02-16); https://www.oblivios.org/ and http://oblivios.org/ answer 308 to https://oblivios.org/; https://oblivios-docs.vercel.app/what-it-does answers 308 to https://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; /nope answers 404.
  • The workstation's resolver returned no address for oblivios.org (getent hosts empty, curl without --resolve gave status 000) and the browser pane's navigation to it failed, while dig against 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 for www, 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 --resolve meanwhile.
  • 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 curl without a login got 404 from all four github.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)

  • gh 2.46 has no --accept-visibility-change-consequences on gh repo edit (unknown flag); the flip is gh api -X PATCH repos/Beau4201/<repository> -f visibility=public, read back with gh api repos/Beau4201/<repository> --jq .visibility and with an anonymous git clone (default branch only).
  • A scratch clone of the private repository for a test of the builder needs git clone --local --no-hardlinks when 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 (the Sitemap: 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 with HEAD and every external link; a script of about 100 lines with urllib does 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 version prints only version 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 --count gives 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 srv tree 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 the SOURCE.md records 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 require AOSP_TREE, EXIT_WORK, VAULT_WORK, PWM_WORK, EXIT_APP_SCRATCH and DNSRESOLVER_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 (the onionmasq sources name three public addresses). The e-mail addresses are the owner's contact in SECURITY.md and 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.jar 40 entries, gradle-wrapper.jar 34 entries; the scan opens an archive because a compressed entry hides its strings). The built output of oblivios.org holds only the contact address, as designed.
  • Git identity: every commit of the four default branches (30, 594, 38 and 173) has author and committer beau4201 with 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 (exiftool is 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) carry date:create, date:modify and date:timestamp text chunks and a tIME chunk 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.png and the AirPods icons carry none. site/shared/public/brand/oblivios-logo.svg holds a <metadata> element with a C2PA manifest (content credentials). Decoded, its claim says Claude provided this file at the request of a user and may have created or modified the file contents, with the generator Claude and the label Anthropic Files, an origin-confidence of unknown, and a c2pa.opened action on an ingredient of type image/svg+xml; it names no logo generator, and the owner confirmed on 2026-11-18 that Claude made the logo. The file is served at https://oblivios.org/brand/oblivios-logo.svg with that manifest; it is kept, as it states the origin correctly (ADR-263).
  • identify -verbose of ImageMagick lists date:create, date:modify and date:timestamp for 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 and security_and_analysis is 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 dev from site/ (the private repository has no sbom/), then npm 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 HTML advisories.html 26.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. An ADR-nnn in a cell is a link when the entry exists; a Markdown link in the log is relative to docs/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 under l, the key that a component uses for its licence: a data hit showed 18 where its licence belonged, and the filter on a licence matched nothing. The length is w.
  • 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 were astro 5.18 (the advisories, which repeat the name in three fields, came before the library) and mit (875 hits, because a typed word of three letters was stretched to mitigation). 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, so GHSA-26w7 listed 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 of oblivios.org) turned a filter bar into a grid of 190 px, .cl (the cloud print) widened a list, .facts stacked the lead of the home page. The portal's own names are tbar, cmpl and dfacts, and the portal copies only the patterns it uses into site/dev/src/styles/pages.css.
  • Overflow [measured]: fifteen pages at 320, 390, 600, 798, 1024 and 1440 px overflowed only on /adr/87 at 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 of minmax(0, 720px) grows to 720 px for a long word instead of shrinking. After overflow-wrap: anywhere on the header band and the facts, three pages (ADR-150, ADR-211, ADR-235) were left, caused by the track; it is minmax(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 and transition: none in 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-content is in Chromium; other browsers open and close without a transition.
  • A local server that sends no Cache-Control let the browser keep the stylesheet of the earlier version, so an animation that was already removed was still seen: serve with Cache-Control: no-store (dev/scripts/serve.mjs does) and give a stylesheet a version in its address while it is a scratch page.
  • The shared changes (Header.astro, Base.astro, areas.mjs of oblivios.org) were checked by building oblivios.org from 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.mjs of the portal differs from that of oblivios.org in 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 any fetch but /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 use placeholder or TODO for what they describe). The count of decision pages must equal the number of rows of the log.
  • A pkill -f with 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 with getBoundingClientRect over the descendants of the page: .prose has margin: auto, which makes a grid item shrink to its content instead of filling its track; an inline code (a path) and the .ev stamp are white-space: nowrap. The portal now sets the side margins of .adr .prose to 0 and lets .adr .prose code, .dfacts code and .adr .ev wrap (overflow-wrap: anywhere); a pre keeps 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, three heading-order (a h3 before any h2: the decision list, the chart on Components, the Shown as written note) and one scrollable-region-focusable (the pre on Verify). The three headings keep their h3 styling and carry aria-level 2 (Entry.astro takes a level), the pre has tabindex="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, stallion and grapheneos baseline put 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 exit puts the data set Compartments exit mask list before the decisions. Weak before a change the same day: mit returned the 424 libraries whose licence is MIT with a long licence expression first (aws-lc-sys), and duress unlock ranked the amendment ADR-210 above the base entry ADR-145. Two rules were added to browse.js (a library whose whole licence is the single typed word gets +5; a decision whose title starts with Amend is multiplied by 0.8); the 27 queries read again gave the same results except that mit now starts with amplify, bail, bincode (licence exactly MIT) and duress unlock gives ADR-147, ADR-145, ADR-233, so the base entry is second and not first. apache-2.0 is 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 by documents.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 .fn link 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 a and .kv a and 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_pane did not change that for this session. Pages were rendered with chromium --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 of oblivios-docs (cp -a first, because the two links sbom/README.md and tools/LICENSE resolve only where those files already are), link site/node_modules into the copy and run npm run build -w dev there: 305 pages and 10,898 links, the same as in the private repository. The copy was not pushed and oblivios-docs was 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.18 stopped finding the library: the tokenizer splits 5.18 into 5.18 and 18, the notes made 5.18 an exact word, and a word that exists was no longer taken as the start of 5.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 and Threat model wrapped, at every width up to 1,630 px, although the pane at 800 px showed the drawer; white-space: nowrap with a smaller gap and two breakpoints (tag, then button) fixed it, read as getClientRects().length of 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), and browse.js puts 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 finding address, while .advd::details-content passed. The rule is written with div, and a comment does not spell the pattern.
  • -webkit-line-clamp on 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: smooth is set on the page: scrollIntoView() and scrollBy() in a measuring script then scroll over time (and not at all while the pane is hidden), so a script that positions the page uses scrollTo({ top, behavior: "instant" }). A requestAnimationFrame loop 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 computer click of the pane, with a listener that logged document.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). The transition that 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, and content-visibility with allow-discrete is 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 advisories grows 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_pane made 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.