SOF-8028: add concept documentation and free docs/ for it

[timurbazhirov]

Ticket: SOF-8028 · Epic: SOF-8025
Plan: plan/review/2026-08-16-concept-documentation.md
Chained onto #417 — review that first; this PR's diff is against feature/SOF-8027.

Eleven pages explaining how ESSE is put together and why, published at schemas.mat3ra.com/docs. The explorer shows you a schema; the map shows you how schemas relate; these pages are the part neither can tell you.

The pages

	Page	What it is for
1	Why ESSE exists	schemas-first vs code-first, and what each paper contributes
2	Schema layering	the build-up from primitives to entities, and why layers stay separate
3	Entity anatomy	root entities, how they compose, and the four-way material variant family
4	Categorization	CateCom tiers, and the *_category vs *_directory split
5	Behavioural mixins	how allOf stacks platform behaviour onto domain payloads
6	Conventions	$ids, includes, generative keys, formatting, URL contracts, the lint rules
7	The pipeline	sources → packages/types/site, and the dual-runtime equivalence contract
8	Consuming ESSE	Python and JavaScript, with runnable snippets
9	Contributing a schema	adding a scalar property, end to end
10	Glossary	the vocabulary in one place

Plus a landing page. The first four are the argument and read in order; the rest are reference.

Documentation that cannot rot

Every count, relationship list and coverage figure is a generated fragment, expanded from graph.json at build time:

<!-- generated:entity-relationships:material -->

renders as

Extends — in-memory-entity/named-defaultable, material/material-properties, material/metadata
Used by — material-enhanced, material-hashed, …

Six fragment types: corpus-totals, layer-inventory, hub-table, mixin-usage, example-coverage, entity-relationships:<id>. Prose stays prose in git; the published pages carry live numbers. An unknown fragment name fails the build, and every page renders before any is written, so a failure never leaves a half-written site.

Schema names throughout link to /map/#/entity/<id>, so a reader can jump from a claim to the thing itself.

The docs/ → site/ rename

Documentation sources and the Pages staging directory cannot both own docs/. The staging directory's name was always incidental — peaceiris publishes its contents to gh-pages, and schemas.mat3ra.com fronts that — so a folder named docs that must not contain docs was a naming bug, not a constraint. It is now site/, gitignored, and docs/ holds the sources.

Two pieces of dead weight went with it:

• build_schemas.py's BUILD_DOCS branch wrote docs/py/** that nothing in CI invoked. Deleted rather than migrated — the JS build is the docs source of truth per the README.
• build_schemas.ts's default BUILD_PATH claimed ./docs/js/, which had not been true for some time. Now ./dist/js/; no behaviour change, since CI sets it explicitly.

Rollback is a single-commit revert; gh-pages history is untouched.

Notes for the reviewer

• No Mermaid. The plan called for it. With the Entity Map shipped, a static diagram box duplicates it worse — the pages link into the live map instead. One fewer CDN dependency.
• marked is in dependencies, not devDependencies, matching json-schema-to-typescript: both are libraries used only by build scripts under src/js/scripts/, which is transpiled and exported.
• Not automated: executing the doc snippets against the built package. They are the README's snippets, already exercised there; a second copy earns little. Not filed as a follow-up.
• Cannot self-certify: the acceptance criteria ask for a newcomer outside the schema team to confirm the 30-minute goal. That review has not happened.

Testing

Built and driven in a browser: 11 pages render, all 11 nav entries present, generated tables expand, zero broken internal links across every page, zero page errors. Verified that an unknown fragment fails the build:

Error: Unknown generated fragment "nonexistent-fragment"

🤖 Generated with Claude Code

---

Generated by Claude Code