Home / Docs / The pack / The Conventions

The Conventions

Three sources govern how this site is built. Read all three before writing code. Where this pack and a source disagree, the source wins and you should say so.

What the guidance requires, quoted

The one minute version, verbatim:

On versioning, specifically. Show the version in the app's chrome, small, in the top bar, always visible, not in a footer or an about box. Make it a link to that version's own details rather than a generic changelog. Give versions a home:

versions/index.json      { "current": "v0.1.0", "versions": [ newest first ] }
versions/v0.1.0.json     { version, date, commit, vault, reconstructed,
                           title, summary, changes[], basis[] }

Record the commit, because a version without it cannot be verified later. Say when reconstructed, because history assembled after the fact must be labelled. And the title is a sentence, not a label: settings move into the right hand column, never UI improvements.

On architecture, the three properties this site must have:

On honesty, which this site will lean on constantly: state the gap rather than papering over it, measured rather than guessed.

On permissions, if any part of this becomes a vault app: deny by default, declare the narrowest permission, and explain each grant. That rule is the ABP's own argument applied to the site that describes it, and it is worth saying so on the page.

What the style guide requires

The style guide documents thirty one rules with measured compliance, and it is honest about its own enforcement: zero linters, formatters or type checkers enforce them, and four structural guards in the pipeline are the only automated enforcement, one of which does not work.

Read it and follow it. Then note the two figures that bear directly on this repository.

File banners are at one hundred per cent compliance. Every file gets one. Match the format used in the sibling repository you copy the pipeline from.

Documents free of em dashes are at zero per cent compliance, with the stated rule violated two hundred and forty eight times across eleven documents. This repository should be the one that does not. Every document in this pack is already free of them. Keep it that way, and consider adding it as a fifth structural guard, since it is the cheapest possible check and the estate has a measured record of failing it.

Other conventions to carry: one idea per file; one class per file, at ninety per cent compliance; empty package initialisers; no underscore prefixed private names; and the constrained primitive patterns where the code is Python.

What to copy rather than invent

You have access to the sibling repositories. Use them. The pipeline, the tagging, the page build and the markdown rendering all exist and are working on live sites.

Copy from one named sibling and say which one in the first commit message. Then verify five things rather than assuming them:

1. The tag is derived from the version file, not typed by hand.
2. The build fails when llms.txt does not list every page. If the sibling does not check this, add it.
3. The custom domain survives a rebuild, meaning the CNAME or its equivalent is written by the build rather than committed once and forgotten.
4. The markdown twin of every page is produced by the build, not maintained alongside it.
5. The version in the chrome comes from versions/index.json, so it cannot drift from the tag.

If any of those five is absent from the sibling, that is a finding and belongs in the first version's notes. The estate's method is to record the gap rather than quietly fix it and move on.

Publishing

Classify the credential before anything becomes public. A read key may be published. A vault key may never be. If any part of this site embeds a vault, escrow the write key before publishing and publish only the read key.

This document is released under the Creative Commons Attribution 4.0 International licence (CC BY 4.0).