docs: add glossary and bootstrap-vs-build docs

docs/concepts/bootstrap-vs-build.rst

@@ -0,0 +1,109 @@
+Bootstrap vs Build
+==================
+
+Fromager has two distinct modes of operation: **bootstrap** and **build**.
+Understanding the difference is key to using fromager effectively.
+
+Quick Comparison
+----------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 40 40
+
+   * - Aspect
+     - Bootstrap
+     - Build
+   * - **Scope**
+     - Entire dependency tree
+     - Single package
+   * - **Purpose**
+     - Discover and resolve all dependencies
+     - Compile source into wheel
+   * - **Recursion**
+     - Yes (processes dependencies)
+     - No (one package only)
+   * - **Input**
+     - Requirements file or package specs
+     - Package name + version + source URL
+   * - **Output**
+     - Dependency graph, build order, all wheels
+     - One wheel file
+
+Bootstrap Mode
+--------------
+
+The ``bootstrap`` command recursively discovers and builds all dependencies:
+
+.. code-block:: text
+
+   fromager bootstrap numpy
+     ├── Resolve version → numpy==1.26.0
+     ├── Download source
+     ├── Build wheel
+     ├── Extract dependencies: [cython, setuptools, ...]
+     └── bootstrap(cython)  ← Recurse for each dependency
+           ├── Resolve version → cython==3.0.0
+           ├── Build wheel
+           └── ...
+
+**Key operations:**
+
+1. Version resolution for all packages
+2. Dependency graph construction
+3. Build order determination
+4. Wheel building (for each discovered package)
+
+**When to use:** Initial discovery of what needs to be built, creating a complete
+wheel collection from scratch.
+
+Build Mode
+----------
+
+The ``build`` command compiles a single package without recursion:
+
+.. code-block:: text
+
+   fromager build numpy 1.26.0 https://pypi.org/simple/
+     ├── Download sdist
+     ├── Apply patches
+     ├── Create build environment
+     ├── Run pip wheel
+     └── Output: numpy-1.26.0-cp311-linux_x86_64.whl
+
+**Key operations:**
+
+1. Source download and preparation
+2. Build environment setup
+3. Wheel compilation
+4. No dependency discovery or recursion
+
+**When to use:** Production builds where the build order is already known
+(from a previous bootstrap), CI/CD pipelines, rebuilding individual packages.
+
+Relationship
+------------
+
+Bootstrap uses build internally:
+
+.. code-block:: text
+
+   bootstrap()
+     └── for each package:
+           └── _build_from_source()  ← Same as build command
+                 └── Creates wheel
+
+The ``build-sequence`` command bridges these modes by reading a ``build-order.json``
+file (produced by bootstrap) and calling build for each package in order.
+
+Typical Workflow
+----------------
+
+1. **Development:** Use ``bootstrap`` to discover all dependencies and create
+   initial wheel collection
+
+2. **Production:** Use ``build-sequence`` with the ``build-order.json`` from
+   bootstrap to rebuild deterministically
+
+3. **Fixes:** Use ``build`` to rebuild individual packages after applying patches
+

docs/concepts/index.rst

@@ -4,5 +4,6 @@ Concepts
 .. toctree::
    :maxdepth: 1
 
+   bootstrap-vs-build
    dependencies