- Decision
- ADR-247
- Date
- 2026-11-17
- Status
- AcceptedAccepted (owner, 2026-11-17: the four public repositories, rich format with diagrams, claims only as proven; two pushes). Done: the READMEs are written and committed; the five Mermaid diagrams render in Mermaid 10.9.3; every relative link of the four READMEs resolves; the SBOM is rebuilt on the pushed commits and its check passes; the four repositories are on
originand stillPRIVATE. Not done: a view on GitHub itself (possible only when a repository is visible to the viewer), new READMEs for the about 25 package directories ofoblivios-platform, the visibility. - Mentions
- ADR-170, ADR-171, ADR-245
1Decision
Rewrite the root READMEs of the four published repositories (oblivios-manifest, oblivios-platform, oblivios-services, oblivios-docs) as professional project pages: a centred title with a one-line purpose and static badges (licence, stage, base), the stage notice, a map of the four repositories and the patch flow as Mermaid diagrams, tables of what each repository holds, a Verify section with commands, a section on what is and is not claimed, security, contributing and licence.
Every sentence is proven by code or a record; stale statements found on the way are corrected (the control protocol version, the advisory and licence-text lines of exit-daemon/README.md, the status and unsafe lines of vault-core/README.md, the patch count of branding/boot, the licence-text line of the SBOM README).
The oblivios-docs README is the string in tools/docs/build-public-docs.py and the SBOM README the string in tools/sbom/build-sbom.py. The four repositories are pushed (the push of the earlier commits and of these, each with the owner's yes).
2Why and evidence
The owner wants the repositories to look like well-kept open-source projects. A precise page is professional because a reader can check it; the stage is source only, so no badge states a build, a release or a coverage figure that does not exist. Rejected: READMEs for all five repositories (oblivios-foundation stays private and has no reader), a minimal README (safe but not what the owner asked for), and a marketing tone such as a privacy-first claim (it conflicts with the claim review of ADR-171 and with the naming criterion of no absolute promise, ADR-170).
3Consequences
The static badges load from a third-party image host; the links between the repositories answer 404 until they are visible; the numbers in the READMEs (19 packages, 344 tests, the lock sizes) are dated or checked by the SBOM build only where it has a claim for them, so a later change to them needs the README edited. This entry completes the push that ADR-245 listed as not done.
4Review when
A claim of a README is found unsupported; a repository changes visibility (look at the rendered page and fix what GitHub shows differently); the owner wants the package READMEs in the same style.
Read from docs/governance/decision-log.md, entry ADR-247.