# coding.sgit.ai — brief pack

**For:** the agent commissioned to build `coding.sgit.ai`
**From:** Dinis Cruz, via the SG/Send Librarian
**Version:** v0.33.62 · 24 August 2026
**Licence:** CC BY 4.0 — the code quoted throughout is **Apache-2.0**. See `LICENSE.md`.

---

## What this is

The coding patterns and formatting across the five languages you work in: **Python, JavaScript, HTML, CSS, Bash.**

Every convention here was **derived from the code by counting**, not from documentation — and where a documented rule and the code disagree, both are reported with the numbers.

---

## The headline

**You already have a written style guide.** `.claude/CLAUDE.md` carries **31 numbered rules** plus 4 non-negotiable testing rules. Measured against 992 class-defining files:

| Rule | Compliance |
|---|---|
| `═══` header on every file | **100%** (992/992) |
| No docstrings, ever | **99.7%** (3 violations) |
| `__init__.py` stays empty | **99%** (299/302) |
| No `_` prefix on private methods | **91%** (97 violations) |

**The site's job is not to invent a style guide — it is to publish the one that exists, with the measurements, and make it enforceable.**

---

## Read in this order

| File | Words | What it does |
|---|---:|---|
| **`00__BRIEF.md`** | 1.2k | **Start here.** The headline, the five languages in a paragraph each, what makes the style unusual, the numbers, the build order |
| **`01__python.md`** | 1.5k | The deepest language. The complete 11-line example, naming families, `Type_Safe`, constrained primitives, alignment, testing, responsibility boundaries |
| **`06__the-rules-and-compliance.md`** | 1.1k | **The page that makes the site useful** — all 31 rules with measured compliance, and the guard that never worked |
| `02__javascript.md` | 1.2k | The framework-free component system, the three-file triplet, the versioned CDN — **undocumented anywhere** |
| `03__html-and-css.md` | 0.9k | Alignment in CSS, design tokens, `data-*` as the behaviour hook, why shadow DOM makes BEM unnecessary |
| `04__bash-and-generated-shell.md` | 0.9k | **Five `.sh` files in 217k LOC** — shell is generated from 15 typed `Section__*` classes |
| **`05__cross-cutting.md`** | 1.3k | What's shared across all five, and **`/for-agents/`** — the most original page available |
| `07__site-architecture-and-boundaries.md` | 1.0k | Page by page, licensing, redaction, network boundaries |
| `08__gaps-and-open-questions.md` | 1.2k | An 8-item enforcement fix list, 7 build-fresh items, 7 open questions, 6 tensions |
| `09__source-manifest.csv` | 20 rows | Every source, tiered 0–3. **Every path verified on disk** |
| `conventions__machine-readable.json` | — | Every count and rule as structured data — for generating the site's pages |
| `LICENSE.md` | — | CC BY 4.0, the Apache-2.0 distinction, and the redaction list |

---

## The four things worth knowing before you write

**1. There is no linter, formatter or type-checker anywhere in the estate.** No mypy, ruff, flake8, black, isort, tox — no config at all. Type safety is enforced *at runtime* by `Type_Safe`, which is a real and defensible choice. The four `tests/ci/` structural guards are the entire automated enforcement surface — **and one of them has never worked**: `test_no_legacy_imports.py` uses `sgraph_ai_service_playwright[^_]`, which cannot match the real double-underscore package. Verified: **0 files matched, 228 real imports across 69 files.**

**2. Four of the five languages have zero documented rules.** All 31 are Python and process. JavaScript, CSS, HTML and Bash have consistent, discoverable conventions that nobody has written down — reconstructing them by counting is most of what `02__`–`04__` did.

**3. Alignment is the estate's most visible convention and its least explained.** Schema attribute colons are **100% aligned**; CSS property values are aligned per block; imports are only **39%**. `05__` §3 makes the argument that alignment is a *machine-readability* decision in a codebase **61% written by an agent** — that is a claim, it is falsifiable, and it should be published as a position with the evidence attached.

**4. Bash barely exists.** Five `.sh` files in 217,266 lines. Shell is **generated** from 15 `Section__*` Python classes, each with a `TEMPLATE` and a `render()`. The trade — testable parameters and no quoting hell, against no `shellcheck` and no directly-runnable script — is worth arguing rather than just reporting. Both mitigations are cheap and neither exists yet.

---

## The most original page available

`/for-agents/` — `05__` §5. Several conventions only make sense once you accept that an LLM is a primary reader and writer:

runtime validation catches a generated mistake at the point of the mistake · constrained primitives encode the domain in the type name · one class per file with filename = class name means a model can locate any symbol by path construction alone · fully-qualified imports with no re-exports means there is exactly one import path to invent · explicit single-owner responsibility rules stop a generator putting a call in a reasonable-looking wrong place · and the markdown twin exists so *"a traversing agent never has to parse HTML."*

There is even direct evidence in the filenames: `library/dependencies/osbot-utils/type_safe/v3.1.1__**for_llms**__type_safe__testing_guidance.md`.

This connects straight to `open-source.sgit.ai` — that site has the argument, this one has the artefact.

---

## House pattern

Copy `pki.sgit.ai`, add the `/llms-full.txt` it lacks, and add one 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.**

A style guide whose examples have drifted from the code is worse than no style guide.

---

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