Test, rewrite, and consolidate schema guide

[danabauer]

Type

Task

Scope

Multi-theme or Platform

Skillset

engineering

Description

What

The repository's Python documentation is spread across two top-level files that nothing
links to, and neither has been checked against the code it describes.

• PYDANTIC_GUIDE.md — 1,362 lines on authoring schema models
• README.pydantic.md — 233 lines mixing project rationale, consumer instructions, and
  contributor setup

Neither is referenced by any file in the repo, and README.md does not mention the Python
packages at all. GLOSSARY.md covers six data-model terms and nothing about the packages,
and is also unreferenced.

The task is to consolidate these into a single guide, verify it by execution, and link it
from README.md and CONTRIBUTING.md.

Why

Three separate problems, and consolidating fixes all of them at once:

1. Nobody can find the docs. There is no path to either file except browsing the file
   listing.
2. Nobody has run the docs. Both files contain code that has never been executed
   against the current packages, so there is no way to know how much of it still works.
3. The mixed audiences make the docs impossible to maintain. Rationale, consumer
   instructions, and contributor setup are interleaved, so no part can be corrected
   without touching the others.

Scope

• Consolidate into one guide, with consumer and contributor material clearly separated
• Execute every command and code block in it; fix or remove whatever fails
• Expand GLOSSARY.md to cover the toolchain vocabulary the guide relies on, and
  cross-link the two
• Link every remaining top-level doc from README.md or CONTRIBUTING.md
• Delete the files that get absorbed

Out of scope: the package-level READMEs under packages/, which have their own set of
inaccuracies tracked separately.

Acceptance criteria

• One guide, linked from README.md and CONTRIBUTING.md.
• Every code block in it has been executed against the repo, and the guide says so.
• Consumer and contributor material are separated, not interleaved.
• GLOSSARY.md defines the terms the guide uses without explanation.
• No top-level markdown file is unreachable from README.md or CONTRIBUTING.md.
• PYDANTIC_GUIDE.md and README.pydantic.md are gone, their content absorbed.