- Decision
- ADR-268
- Date
- 2026-11-19
- Status
- AcceptedAccepted (owner, 2026-11-19: the mockups were approved and the owner said to make the site; to the questions of the same day: only the designed pages, search must work and be extremely good, and the source line stays as an exception for
oblivios.dev). The calls of the agent are the names and prints, the proof blue, the order of the pages, the ranking of the search, the paging by 20 and the choice to write the little markup renderer instead of adding a package; the owner may overrule each. - Mentions
- ADR-028, ADR-030, ADR-087, ADR-125, ADR-126, ADR-127, ADR-165, ADR-250, ADR-251, ADR-252, ADR-254
- Mentioned by
- ADR-269, ADR-270, ADR-271
Shown as written
This entry has 8 columns where the log has seven, because a cell holds the separator of the table or a column is missing. The cells follow in their order, under the label of their place.
1Decision
Build the developer portal oblivios.dev as the Astro application site/dev, after the owner approved its mockups on 2026-11-19 (gate W-1 is met for oblivios.dev; ADR-252 left it open).
(1) Direction: the family of oblivios.org (ADR-251: tokens, layout, type, paper, stamps) with an accent of its own, proof blue for what has been read and checked (links, the page you are on, an accepted decision) while brick stays for the prints and for what is open (a proposed decision), and eight prints drawn for the portal (an open ledger with a lens, a ledger, a sealed sheet, a cracked shield, a crate, a notebook, a terminal, a stack of sheets) instead of the nineteen of oblivios.org.
(2) Pages of this build: Home, Decisions (paged by 20, with a page for every entry of the log at /adr/<n>), Search, and the bill of materials as five pages under Components: Components, Advisories, Files and patches, Data and Verify. The threat model, the engineering notes and the quickstarts of spec 5.1 are not in this build and are not linked, because none has a design or a claim review.
(3) Everything is read from the repository at build time: the decision log from docs/, the SBOM from sbom/ (SBOM_DIR where the repository has none), the contact from SECURITY.md; a push of the oblivios-docs snapshot is the only step that changes the portal.
(4) One script, /browse.js, written as plain readable source, does the search and the filters: it fetches /search-index.json (written by the build from the decisions, components, advisories, data sets and files) from its own origin and stores nothing. The Content-Security-Policy is that of oblivios.org except form-action 'self', which the search form needs.
check-build.mjs allows exactly that one script and fails on any other script, on storage, on another network API, on dynamic code and on a fetch of anything but the index. (5) A decision page and each page of the bill of materials carries one line Read from that links the file in the published repository: an exception to the rule of ADR-251 that no page lists its sources, for this site only, because the portal exists to show where a fact comes from.
(6) The shared package changes without changing oblivios.org: the header takes a name and the portal button has no arrow, Base.astro takes slots for the prints and the head and a flag that turns the page-view counter off (the spec counts views on oblivios.org only, so the portal counts none), and the nine parts become one list in site/shared/src/lib/parts.mjs.
(7) The eight entries of the log that do not have seven columns (ADR-028, ADR-030, ADR-087, ADR-125, ADR-126, ADR-127, ADR-165, ADR-254) are shown as written, with a note on the page.
2Why and evidence
The owner asked for a portal for reviewers, developers and anyone who wants to see what and how, in the style of oblivios.org, with as much information as the site can hold without being too much or ugly; the first mockups (ADR-250) were rejected as ugly.
The mockups of 2026-11-19 went through the owner's flags in rounds: an arrow after a link was called an AI arrow and is a button instead; a disclosure animates on closing only; a page is read at the half screen (about 800 px) and at the size of an iPad; two adjacent bands in one colour read as one and now alternate; a dark band was too heavy in the light scheme; the filters were redrawn as chips and stamps; the components page held too much and became five pages with a sub-navigation.
[measured: node over the build] the log has 267 entries of which 181 are accepted and 60 proposed, and the SBOM 1,238 components, 1,567 files and 27 advisories.
Rejected: building the threat model, engineering and quickstart pages now (no design and no claim review, and a page without both is what the owner rejected twice), a search that is only drawn (it breaks the owner's rule that a designed control works, and the owner asked for an extremely good one), a search library such as Pagefind or Fuse (a new npm component with licence and advisory evidence for the SBOM, and the spec allows no external service), a Markdown package for the cells (the table is the owner's own and the subset is six constructs), dropping the source line (the owner chose to keep it), the prints of oblivios.org (the owner wants prints that fit where they stand), one long components page (the owner found it too much and ugly), the docs theme of the spec (it is not a package of the lockfile).
3Further text
site/dev builds 289 pages (the 267 decisions, the lists, the search and the bill of materials), and check-build.mjs passes with 7,676 links; the output of oblivios.org is unchanged by the shared changes except one extra space in the header markup [measured: a build of the stashed tree and a diff of the HTML before and after].
The search index has 2,914 documents, 11,214 words and 87,500 postings, 1.5 MB raw and about 460 KB gzipped [measured: node over the build], and a search takes 1 to 5 ms in the browser pane [measured].
On a test set of 23 queries the expected entry was in the first three for 21 before three ranking fixes (an exact component name 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 none has them all); the set was not run again after the fixes [measured].
The filters and the search of the decision list and of the components page were driven with scripted events and gave the expected counts (60 proposed, 8 of them in Compartments, 4 with measured evidence, 13 libraries with advisories, 3 sources that are not in the repositories) [measured].
Fifteen pages at 320, 390, 600, 798, 1024 and 1440 px overflowed only on one decision page at 320 and 390 px; a sweep of all 267 decision pages at 320 px found long words that pushed three pages wider, the CSS was changed and built, and the re-run of the sweep did not finish and was made later the same day (engineering notes).
Not done: the dark scheme and the phone of the real build by eye beyond the home page at 375 px (the sweep and axe of 2026-11-19 are in the engineering notes); Safari and Firefox (the closing animation uses ::details-content, which Chromium has); the claim review of the portal copy (C-1) and of the Read from lines; the check that tools/sbom/build-sbom.py and tools/docs/build-public-docs.py accept the new workspace, the file types of site/dev and the lockfile entry (no package was added, so site/NOTICE should not change); the Vercel project with root site/dev and its settings, the DNS and CAA of oblivios.dev (the owner's account, W-3, D-1); the regeneration and push of the snapshot; the link to the portal on oblivios.org (portal in site/org/src/lib/site.mjs stays null until the portal is live).
The mockups were scratchpad pages and are not kept: the build is the design.
4Further text
The log is read whole at build time, so a table that changes its shape fails the build with the entry named; a decision that is added or amended is a page at the next build. The portal has one script of its own, which is a deviation from oblivios.org that the privacy rules of 5.4 did not foresee; the rules otherwise hold (no cookie, no storage, no request to another origin, self-hosted fonts, no page-view count). A search over 267 decisions and the SBOM is a client-side ranking, not an index service: its size grows with the log, and the budget of the check is 2.2 MB raw. The claim review has not run on the new copy, so no sentence of the portal counts as proven yet.
5Last cell
The owner rejects a page, a print, the proof blue or the search ranking; the index outgrows its budget or a phone cannot fetch it; a sentence of the portal is found unsupported in the claim review; the portal needs a second script; a package for search or Markdown becomes worth its SBOM entry; the threat model, engineering or quickstart pages are designed.
Read from docs/governance/decision-log.md, entry ADR-268.