Add schema orientation section to generated docs (v0.1) (#205)

The autogen metadata page currently jumps from the one-paragraph
schema description directly into an alphabetical class table, which
makes MaterialSampleRecord look like an equal sibling to supporting
types like IdentifiedConcept or Agent.

Adds a hand-written "How this schema is organized" section to the
index template, grouping the 8 core classes into: the centerpiece
(MaterialSampleRecord), the act of sampling (SamplingEvent /
SamplingSite / GeospatialCoordLocation), post-collection life
(MaterialSampleCuration, SampleRelation), and supporting types
(Agent, IdentifiedConcept). Concludes with a one-sentence "putting
it together" walk-through for a typical record.

The autogen reference tables remain below as the complete source of
truth — this only adds narrative scaffolding above them.

Addresses #204

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: rdhyee

tools/docgen/index.qmd.jinja2

@@ -9,6 +9,74 @@ date-modified: {{ gen.timestamp }}
 URI: {{ schema.id }}
 Name: {{ schema.name }}
 
+## How this schema is organized
+
+The autogenerated reference below lists every class, slot, enumeration, and type
+alphabetically. For newcomers, that flat list can obscure the fact that the
+schema has a clear conceptual center and that most other classes exist to
+describe the context around it. This section is a hand-written orientation to
+help you find your way in.
+
+### The centerpiece: the sample record
+
+[**MaterialSampleRecord**](./MaterialSampleRecord.html) is the schema's core
+class. It is the digital record *about* a physical material sample — a rock
+core, a sherd of pottery, a biological specimen, a sediment grab. Every other
+class in the schema exists to describe *something about* a MaterialSampleRecord:
+how it was collected, where, by whom, what it is, and what has happened to it
+since.
+
+### The act of sampling
+
+A sample doesn't exist in isolation — it was produced by some act of sampling
+at some place and time. Three classes capture this:
+
+- [**SamplingEvent**](./SamplingEvent.html) — the event that produced the
+  sample (who did it, when, under what authorization, following which protocol).
+- [**SamplingSite**](./SamplingSite.html) — documentation of the place the
+  sample was collected from, including place name(s) and the broader context it
+  is part of.
+- [**GeospatialCoordLocation**](./GeospatialCoordLocation.html) — decimal
+  latitude/longitude and elevation, used both for the sample's precise
+  coordinates and for the centroid of a sampling site.
+
+### After collection: curation and relationships
+
+Once a sample leaves its original context, it has an ongoing life in
+collections, analyses, and derived artifacts:
+
+- [**MaterialSampleCuration**](./MaterialSampleCuration.html) — where the
+  sample is currently kept, how it can be accessed, and the history of its
+  handling.
+- [**SampleRelation**](./SampleRelation.html) — semantic links between
+  samples (e.g. a derived subsample) or between a sample and a related
+  resource.
+
+### Supporting types used across the model
+
+Two classes appear throughout the model rather than being specific to any one
+part:
+
+- [**Agent**](./Agent.html) — a person (or organization) playing a role such
+  as collector, curator, or registrant.
+- [**IdentifiedConcept**](./IdentifiedConcept.html) — a vocabulary term with
+  an identifier and label, used for things like material category, context
+  category, object type, and relationship kinds.
+
+### Putting it together
+
+A complete record typically looks like:
+*a* [MaterialSampleRecord](./MaterialSampleRecord.html)
+— produced by a [SamplingEvent](./SamplingEvent.html) at a
+[SamplingSite](./SamplingSite.html) with a
+[GeospatialCoordLocation](./GeospatialCoordLocation.html),
+described using [IdentifiedConcept](./IdentifiedConcept.html) vocabulary terms
+for its material and context categories,
+with [Agent](./Agent.html)s named as registrant and responsible parties,
+curated per a [MaterialSampleCuration](./MaterialSampleCuration.html),
+and optionally linked to other samples via
+[SampleRelation](./SampleRelation.html).
+
 {% include "class_overview_diagram.qmd.jinja2" %}
 
 ## Classes