Add 'How these docs are built' documentation-engineering page

Explains the docs-as-engineering approach (Sphinx/Furo, CI-built,
warning-clean under -W, autodoc, grounded-in-code prose). Serves as the
on-site anchor for the documentation-engineering story.

Author: bob7123

docs/source/documentation-engineering.rst

@@ -0,0 +1,77 @@
+========================
+How these docs are built
+========================
+
+This documentation is built as engineering, with the same rigor as the code it
+describes. This page explains how, because how a system is documented is itself
+a signal of how it is built.
+
+.. contents::
+   :local:
+   :depth: 1
+
+Documentation held to a passing bar
+===================================
+
+The site is built with `Sphinx <https://www.sphinx-doc.org/>`_ and the
+`Furo <https://pradyunsg.me/furo/>`_ theme, from reStructuredText sources under
+``docs/source/``. It is compiled and deployed to GitHub Pages by a GitHub
+Actions workflow on every push to ``main``.
+
+The build runs with warnings treated as errors:
+
+.. code-block:: bash
+
+   sphinx-build -b html -W --keep-going docs/source docs/_build/html
+
+The ``-W`` flag is the point. A broken cross-reference, a malformed heading, or
+a link to a page that no longer exists does not produce a quiet warning that
+rots over time; it fails the build, exactly like a failing test. The
+documentation passes or it does not ship. This is what keeps a docs site honest
+as the code underneath it changes.
+
+Reference that cannot drift
+===========================
+
+The API reference is generated directly from the source with Sphinx autodoc. It
+reads the actual classes, signatures, and docstrings out of the installed
+package rather than restating them by hand. Hand-copied API docs drift from the
+code the moment the code changes; generated ones cannot, because the code is
+their only source.
+
+Prose grounded in the code
+==========================
+
+The technology chapters are not generic tutorials. Each was written against the
+specific module that uses the library in question, and describes how it is
+actually used here, not how it is used in the abstract. The same discipline
+applies to the concept chapters: where the tool has a known limit, the docs
+state it plainly rather than imply a capability the code does not have. The
+:doc:`concepts/schema-adaptation` chapter documents its own classification edge
+cases; the :doc:`concepts/privacy` chapter names the guarantees it does *not*
+make. Documentation that hides limits is documentation that cannot be trusted on
+the claims it does make.
+
+Structure
+=========
+
+The site is organized by what a reader is trying to do, not by how the code is
+packaged:
+
+- **Getting Started** gets a reader from nothing to generated data.
+- **Concepts** explains the design decisions and why they were made.
+- **Foundations** covers the principles and the project's lineage.
+- **Technology Stack** justifies each dependency in the context of the system.
+- **Reference** is the exhaustive, lookup-oriented material (CLI, API, testing).
+
+Diagrams are authored as text (Mermaid) and rendered in-page, so they live in
+version control alongside the prose and change with it.
+
+Why this matters
+================
+
+Treating documentation as a versioned, reviewed, CI-gated part of the project,
+rather than an afterthought, is a deliberate practice. It is the difference
+between a README that describes what the software was intended to do on the day
+it was written, and a documentation system that is held accountable to what the
+software actually does today.

docs/source/index.rst

@@ -88,6 +88,12 @@ Contents
    reference/api
    reference/testing
 
+.. toctree::
+   :maxdepth: 1
+   :caption: About the documentation
+
+   documentation-engineering
+
 Project information
 -------------------