coding.sgit.ai — how software actually gets written here

The sgit.ai network's site about coding style: five languages — Python, JavaScript, HTML, CSS, Bash — as they are actually written across 217,266 lines. Every convention was derived by counting the code, not from documentation, and where a documented rule and the code disagree, both are published with the numbers.

Live site: https://coding.sgit.ai (GitHub Pages, deployed from dev).

The headline

31 documented rules. 0 linters. 4 CI guards, and a 5th that has never worked.

Measured against 992 class-defining files: banners 100%, no-docstrings 99.7%, empty __init__.py 99%, one-class-per-file 90%, no-underscore-private 91%. Import alignment is 39% and is not a documented rule at all. The broken guard's regex is sgraph_ai_service_playwright[^_], and [^_] cannot match the real package sgraph_ai_service_playwright__cli — 0 files matched, against 228 real imports across 69 files.

Structure

• index.html / index.md — the front page and its markdown twin
• style/ — what is shared across all five languages: one idea per file, banners, the alignment argument, single source of truth enforced by structure
• python/, javascript/, html/, css/, bash/ — one page per language
• rules/ — all 31 rules plus the 4 testing non-negotiables, with measured compliance and an enforcement badge. Generated from data/rules.json
• enforce/ — the linter and guard configs, shipped as real files, plus an honest account of what ruff, eslint and stylelint genuinely cannot express
• shipped/ — what is not enforced. The bad numbers, in one place
• for-agents/ — the conventions that only make sense once an LLM is a primary reader
• open-questions/ — 8 questions, 6 tensions, 7 loose ends, published unresolved
• documents/ — reader pages for the 13 source documents, generated from data/documents.json
• briefs/ — those source documents, verbatim (see Redaction below)
• network/, about/, admin/ — boundaries, disclosure, and how this site is built
• assets/site.css — the shared stylesheet (sgit.ai design language)

Build tooling

File	Owns
admin/build/version.txt	The version — single source of truth
admin/build/chrome.py	The single definition of the nav and footer, rewritten across every page
admin/build/pagelib.py	The shared page shell and the write-or-check writer
admin/build/gen_documents.py	documents/ from data/documents.json and briefs/
admin/build/gen_rules.py	rules/index.html from data/rules.json
admin/build/gen_inline.py	Every number and every code example on every page
admin/build/gen_llms_full.py	llms-full.txt from llms.txt, index.md and briefs/
admin/build/gen_sitemap.py	sitemap.xml from the tree
admin/build/validate.js	The release gate: version, links, canonical, leak tripwire

Python 3 and Node, both stdlib-only. Nothing to install.

gen_inline.py — the rule this site is held to

The commissioning brief adds one house rule specific to this site:

Every code example and every count is extracted from the repo at build time, with a path and a commit reference.

This repository holds the website, not the 217,266 lines it describes, so build-time extraction is not available. What is in place instead: no number and no snippet on this site is typed by a person. A page carries a placeholder —

<span class="cnt" data-k="python.files"></span>
<figure class="src" data-src="01__python.md" data-block="0" data-path="…/Schema__Caller__IP.py"></figure>

— and gen_inline.py fills both in place, the way chrome.py fills the nav: the figure from briefs/conventions__machine-readable.json, the example from the published document it was quoted in, with its real path and its own Apache-2.0 notice attached. --check fails the release if any has drifted.

That closes drift within the site and leaves freshness open: the survey is dated (2026-08-24), not live. Tracked as R2 in admin/comms.html and stated on the site at /shipped/#drift.

Redaction

Two of the thirteen source documents carry the brief pack's own do-not-publish list, which names the values it forbids. In those two files only — 07__site-architecture-and-boundaries.md and LICENSE.md — an AWS account id, four live internal hostnames and four named live stack FQDNs are replaced with [redacted]. Occurrence counts are kept, each change is marked in place, and the change is described at /documents/#redaction.

dev.tools.sgraph.ai is deliberately not redacted: it appears inside the code examples, and a component example with its import URL removed teaches nothing. That is open question Q4.

The leak tripwire gained an AWS-account-id shape (a bare 12-digit number) so the value cannot return. Note what the pattern is not: it does not contain the account id. A tripwire that hard-codes the secret it looks for has published the secret in the tripwire.

Release process

1. Bump admin/build/version.txt (vX.Y.Z, exactly once per release) and add a row to admin/versions.html; update admin/comms.html if anything changed.
2. Regenerate the pages: python3 admin/build/gen_documents.py && python3 admin/build/gen_rules.py.
3. python3 admin/build/chrome.py — propagates the version badge and any nav/footer change to every page, generated ones included, and stamps the version into llms.txt and index.md.
4. python3 admin/build/gen_inline.py — after the generators, because it writes into pages they have just produced.
5. Regenerate the files that read the tree and those stamped twins — after chrome, or they assemble a stale version line: python3 admin/build/gen_llms_full.py and gen_sitemap.py.
6. Validate exactly what CI runs:

   python3 admin/build/gen_documents.py --check
   python3 admin/build/gen_rules.py     --check
   python3 admin/build/gen_inline.py    --check
   python3 admin/build/gen_llms_full.py --check
   python3 admin/build/gen_sitemap.py   --check
   node admin/build/validate.js
   

7. git commit -am "site vX.Y.Z: ..." && git push -u origin dev

Every push to dev runs .github/workflows/deploy-pages.yml: validate → auto-tag (vX.Y.Z, verified against version.txt and the commit subject, next-minor enforced) → deploy to GitHub Pages. Pull requests run validation only. A push to main validates and deploys without tagging. Same pipeline as SGit-AI__Website, SGit-AI__Website__Graphs and SGit-AI__Website__SG-Compute.

One inherited trap, pre-empted

The Python .gitignore this repository starts from carries build/, which silently swallows admin/build/ — a sibling site shipped a first release whose validate job died on a missing file before it could check anything. The !admin/build/ negation is in this repository's first commit.

Licence

All site content CC BY 4.0 — Dinis Cruz, with AI co-authorship (Claude, Anthropic).

The code quoted throughout is Apache-2.0 and carries its own notice on every example; it is not covered by this site's licence. Type_Safe, Safe_Str, Safe_Int and the constrained-primitive pattern come from osbot-utils, Apache-2.0, under the owasp-sbot organisation — the convention is the estate's, the mechanism is the dependency's, and on a site about attribution discipline that distinction is the point.