The source documents
Everything on this site is written from its source documents, and they are published in full — 13 of them, 12,983 words — because a site that argues from a document should let you read the document.
The raw markdown is the source of truth. Each reader page renders its document
from the raw file in briefs/ at load time; if that fails, the page falls back
to a link to the raw file. Nothing is transcribed by hand, so a reader page cannot say
something the document does not.
Every file is fetchable at a stable constructed URL: /briefs/<filename>.
That is a promise, not an accident.
Read them
The brief pack — read me first
What the pack is, the headline finding, the reading order, and the four things worth knowing before writing a line: no linter anywhere, four of five languages undocumented, alignment as the least-explained convention, and bash barely existing.
Read it →00 — The brief
The commission itself. The five languages in a paragraph each, the three things that make the style unusual, the honesty constraint, the numbers, and the build order this site was written in.
Read it →01 — Python
The deepest language and the only one with written rules behind it. The complete eleven-line example, the naming families, Type_Safe, constrained primitives, alignment, testing, and the responsibility boundaries.
Read it →02 — JavaScript
The framework-free component system, the three-file triplet and the versioned CDN — undocumented anywhere until this pack counted it. Plus the four inconsistencies to settle before it can be a standard.
Read it →03 — HTML and CSS
Alignment carried into CSS, design tokens, data-* as the behaviour hook, the markdown twin, and why shadow DOM makes BEM unnecessary.
Read it →04 — Bash and the generated-shell pattern
Five .sh files in 217,266 lines. Shell is generated from fifteen typed Section__* classes, and the trade that makes is worth arguing rather than just reporting.
Read it →05 — What is shared across all five
One idea per file, banners, the alignment argument, single source of truth enforced by structure, and the section that became the for-agents page: the conventions that only make sense once an LLM is a primary reader.
Read it →06 — The 31 rules, and whether the code obeys them
The measurement nobody had made. Every rule group with its compliance, the five places the code and the docs disagree, and the CI guard that has never worked.
Read it →07 — Site architecture, licensing and boundaries
Page by page, the licensing distinction between this site's CC BY 4.0 and the Apache-2.0 code it quotes, the redaction rules, and the network boundaries. Published with its own redaction list redacted.
Read it →08 — Gaps, open questions and honest tensions
An eight-item enforcement fix list, seven things nobody has written, seven open questions and six tensions. The source of the open questions page, published unresolved.
Read it →The pack's licence and redaction rules
CC BY 4.0 for the pack and this site, Apache-2.0 for the code quoted throughout, credit to osbot-utils for the Type_Safe pattern, and the redaction list. Published with that list redacted.
Read it →All 13, with their raw files
What was redacted, and what was not
Two documents are published with their own redaction lists redacted. Everything else is verbatim. Two of the documents listed above carry the pack's own
do-not-publish list, which names the values it forbids. Publishing that list verbatim
would publish them, so in those two files — and nowhere else — the following are replaced with
[redacted]:
- the AWS account id named in the pack's do-not-publish list
- four live internal hostnames, with their occurrence counts kept
- four named live stack FQDNs, with the count kept
The occurrence counts are kept, because the counts are the point of the list and they leak nothing. Each change is marked in place in the document, so a reader can see exactly where the text was altered rather than having to trust that it was not altered elsewhere.
One thing was deliberately not redacted. dev.tools.sgraph.ai, deliberately — it appears inside the code examples and a component example without its import URL teaches nothing. See open-questions Q4.
The release gate encodes the rule as well as the site stating it: the leak tripwire fails the build on anything shaped like a vault key, an AWS access key id, a GitHub token, an API secret, a private key block, a Slack token — or an AWS-account-id-shaped 12-digit number, which is the pattern this release added. The fix for a tripped wire is to redact the snippet, never to widen the pattern.
Licence
Every document, and every page of this site, is released under CC BY 4.0. Attribution: Dinis Cruz, with AI co-authorship (Claude, Anthropic). Where the site quotes source code, it quotes it under that code's own licence; those notices are retained and the snippets do not carry this site's licence.