docs: the ecosystem side — payloads, adapters and board-support packages

The assessment of the finished book found a fourth reader the design had missed,
and the measurement that found them is the sharpest in this batch:

  `xim:` payloads are named 84 times across 12 chapters.
  How to make one is explained nowhere.
  `xim-pkgindex` appears 17 times, all in the chapter about releasing mcpp.

Every toolchain, device toolkit, shader compiler and emulator in this ecosystem
is a payload. The documentation taught all of consuming them and none of
producing them, and the omission was hidden by how often they are mentioned. Two
more of the same shape: a `compat:` runtime adapter is named in four chapters
and authored in none, and a board-support package is described from the
consumer's side in 40 and 41 with no chapter on writing one.

Three chapters, and `3x` becomes "extending mcpp and its ecosystem":

  32  Authoring a Payload                 what an xim: descriptor must say, the
                                          two mirrors, `latest` as a reference,
                                          the exports that write a consumer's
                                          RPATH, and the `when` tier
  33  Authoring a Runtime Adapter         why a dlopen fails against a library
                                          that is plainly installed, and what a
                                          symlink farm plus runtime.library_dirs
                                          fixes
  34  Authoring a Board-Support Package   one package and two environments, the
                                          zero-libc tier, the machine table that
                                          is not a default, and run_exclusive

Every fact is read out of a published package -- glslang.lua,
compat.vulkan-runtime.lua, cortex-m-rt -- rather than out of the mechanism.

The adapter chapter records a decision that is not a packaging choice: a
proprietary driver's userspace is in ABI lockstep with a kernel module and its
licence forbids redistribution, so it is a host capability and the adapter is
how an artifact reaches it. An open driver is a payload and needs no adapter.
Which answer applies is decided by the licence and the ABI, not by preference.

Scenario 10 and a role-index row carry the new reader; the lookup index gains
`xim:` and `compat:`.

Author: speak-agent

.agents/docs/2026-09-08-the-documentation-as-a-book.md

@@ -395,3 +395,57 @@ belongs to `9x` or to SPEC-004. Both were named in §6 and neither is moved yet.
 reference chapter's own section list, so a key added to `04` and not indexed is
 invisible. The check is the same shape as rule 4 (every specification appears in
 every index) and is one loop.
+
+---
+
+## 12. The ecosystem side, which the first design missed
+
+§5 designed the book for three readers — someone using mcpp, someone extending
+one project's build, and someone changing mcpp. It missed a fourth, and the
+measurement that found it is the sharpest in this record:
+
+> `xim:` payloads are named **84 times across 12 chapters**. How to make one is
+> explained **nowhere**. `xim-pkgindex` appears 17 times, all of them in the
+> chapter about releasing mcpp itself.
+
+Every toolchain, every device toolkit, every shader compiler and every emulator
+in this ecosystem is a payload. The documentation taught the whole of consuming
+them and none of producing them, and the omission was hidden by how often they
+are mentioned.
+
+Two more of the same shape: a `compat:` runtime adapter — the layer that makes a
+host library reachable from an artifact on Linux — is named in four chapters and
+authored in none; and a board-support package is described from the consumer's
+side in `40` and `41` with no chapter on writing one.
+
+### 12.1 Three chapters, and the band they complete
+
+`3x` was "extending the build graph" and is now **extending mcpp and its
+ecosystem**: the two scales of one project's own step, then the three kinds of
+package that serve everyone else.
+
+| # | chapter | reader | the one question | excludes |
+|---|---|---|---|---|
+| 32 | Authoring a Payload | someone packaging a tool or a prebuilt library | what is an `xim:` payload made of, and what must its descriptor say | source packages (11), host libraries (33) |
+| 33 | Authoring a Runtime Adapter | someone making a host-supplied library reachable | why an artifact cannot see a library that is installed, and what fixes it | anything redistributable, which is a payload (32) |
+| 34 | Authoring a Board-Support Package | someone bringing up a board | what does a BSP supply, and how does one package serve an emulator and hardware | using a BSP (40), the runner a consumer sees (41) |
+
+Each is written from a real published package rather than from the mechanism:
+`xim-pkgindex/pkgs/g/glslang.lua`, `mcpp-index/pkgs/c/compat.vulkan-runtime.lua`,
+and `mcpplibs/cortex-m-rt`. Every fact in them was read out of those files.
+
+### 12.2 The decision the adapter chapter records, which is not a packaging choice
+
+A proprietary driver's userspace is in ABI lockstep with a kernel module and its
+licence forbids redistribution. Neither is solved by effort, so it is modelled
+as a **host capability** and the adapter is how an artifact reaches it. An open
+driver takes the other answer — it is a payload, and a machine using one needs
+no adapter. **Which answer applies is decided by the licence and the ABI, not by
+preference**, and that is the sentence a reader of scenario 10 leaves with.
+
+### 12.3 What this changes about §5's claim
+
+§5 said 24 chapters for a tool that is three tools is not too many. The count is
+31 now, and the reason is that the tool is four things rather than three: a
+build system, a package manager, a toolchain provisioner, **and an ecosystem
+other people publish into**. The fourth had no chapters at all.

docs/02-scenarios.md

@@ -28,6 +28,7 @@ people. Read only the scenario that matches; they do not build on each other.
 | [7](#7-compute-on-a-gpu-or-an-accelerator) | compute on a GPU or an accelerator | `examples/09-heterogeneous` |
 | [8](#8-graphics-rendering) | graphics rendering | `examples/10-graphics/offscreen` |
 | [9](#9-a-build-step-the-project-needs) | a build step the project needs, and sharing it | `examples/08-build-rules`, `12-a-new-device-language` |
+| [10](#10-packaging-a-tool-a-driver-or-a-board) | packaging a tool, a driver or a board for others | the descriptors in `xim-pkgindex` and `mcpp-index` |
 
 ## 1. A command-line tool or service
 
@@ -253,6 +254,36 @@ step. Without that, editing the generator leaves every edge clean and the
 artifact keeps the bytes the previous generator produced — a green build over a
 stale result.
 
+## 10. Packaging a tool, a driver or a board
+
+**The situation.** Something other projects should be able to declare and get:
+a compiler, a shader compiler, an emulator, a host graphics driver, a board.
+
+**What mcpp contributes.** A consumer declares it by name and gets a working
+program — the payload is installed, its libraries are on the artifact's search
+path, and the tier decides whether a build that never runs pays for it at all.
+
+**The path.**
+
+1. [32 — Authoring a Payload](32-authoring-a-payload.md) — a tool or a prebuilt
+   library mcpp installs.
+2. [33 — Authoring a Runtime Adapter](33-authoring-an-adapter.md) — when the
+   library belongs to the host and cannot be redistributed.
+3. [34 — Authoring a Board-Support Package](34-authoring-a-bsp.md) — a board,
+   its memory map, and the way in.
+4. [31 — Authoring a Rule Package](31-authoring-a-rule-package.md) — if a build
+   step drives the tool.
+
+**Run.** The descriptors themselves: `xim-pkgindex/pkgs/g/glslang.lua` for a
+payload, `mcpp-index/pkgs/c/compat.vulkan-runtime.lua` for an adapter,
+`mcpplibs/cortex-m-rt` for a board.
+
+**What surprises people.** Which answer applies is decided by the licence and
+the ABI, not by preference. A driver whose userspace is in lockstep with a
+kernel module and whose licence forbids redistribution **cannot** be a payload;
+it is a host capability, and the adapter is how an artifact reaches it. An open
+driver is a payload, and a machine using one needs no adapter at all.
+
 ## Current limitations
 
 - The scenarios here are the ones with a runnable project or a published

docs/32-authoring-a-payload.md

@@ -0,0 +1,139 @@
+# 32 — Authoring a Payload
+
+**Reader:** someone packaging a tool or a prebuilt library so that mcpp projects
+can declare it and mcpp installs it.
+
+**The question this chapter answers:** what is an `xim:` payload made of, and
+what must its descriptor say for a consumer to name it and get a working
+program.
+
+**Not here:** publishing a **source package** others `import`, which is
+[11 — Publishing a Library](11-publishing-a-library.md); making a **host**
+library reachable from an artifact, which is
+[33 — Authoring a Runtime Adapter](33-authoring-an-adapter.md); and consuming a
+payload, which is [23 — The Project Environment](23-the-project-environment.md).
+
+Before: [31 — Authoring a Rule Package](31-authoring-a-rule-package.md), whose
+rules declare the payloads they drive. After:
+[33 — Authoring a Runtime Adapter](33-authoring-an-adapter.md).
+
+## What a payload is
+
+Everything mcpp installs and does not compile: a compiler, a shader compiler, a
+device toolkit, an emulator, a probe driver, a prebuilt C library. A project
+names one in `[xlings.workspace]`, or a rule package names it in
+`[feature-xlings.<f>]`, and mcpp provisions it before the build runs.
+
+A payload lives in `xim-pkgindex` as one Lua file: a `package` table that
+describes it, and two functions that place and register it.
+
+The shortest one that works:
+
+```lua
+package = {
+    spec = "2",
+    name = "glslang",
+    description = "Khronos reference GLSL/ESSL front end and validator",
+    licenses = {"BSD-3-Clause", "Apache-2.0", "MIT"},
+    type = "package",
+    archs = {"x86_64"},
+
+    xpm = {
+        linux = {
+            ["latest"]  = { ref = "15.1.0" },
+            ["15.1.0"]  = {
+                url = {
+                    GLOBAL = "https://github.com/…/glslang-15.1.0-linux-x86_64.tar.gz",
+                    CN     = "https://gitcode.com/…/glslang-15.1.0-linux-x86_64.tar.gz",
+                },
+                sha256 = "87167c9cb32f258addbedb607639b2c1f484c029ba91542a92f19ead21d65d13",
+            },
+        },
+    },
+}
+
+function install()
+    local dir = pkginfo.install_dir()
+    os.tryrm(dir)
+    os.mv("glslang-15.1.0", dir)
+    return true
+end
+
+function config()
+    xvm.add(package.name)
+    return true
+end
+```
+
+`install()` places the extracted tree where mcpp will look for it; `config()`
+registers what the payload offers. Everything else in this chapter is one of
+those two doing more.
+
+## The four things a descriptor must get right
+
+**One version, two URLs.** Every version carries a `GLOBAL` and a `CN` URL and
+one `sha256`. The two mirrors serve the same bytes; a consumer behind either
+mirror resolves the same hash, and a descriptor with one URL is unusable for
+half the ecosystem.
+
+**`latest` is a reference, not a version.** `["latest"] = { ref = "15.1.0" }`.
+It is what a consumer gets when it names no version, and moving it is a
+deliberate act — a consumer pinned to `15.1.0` is unaffected.
+
+**`archs` and the platform table are what a resolution reads.** A payload
+published only for `linux` and `x86_64` says so, and a consumer on another
+platform is refused by name rather than handed something that will not run.
+
+**Dependencies are `xim:` addresses with floors.**
+
+```lua
+deps = { "xim:gcc-runtime@>=15", "xim:glibc@>=2.38" },
+```
+
+## Making the payload reachable
+
+A payload that only unpacks is not usable. Three declarations turn a directory
+into something a build can consume.
+
+**A program on the path.** `xvm.add(package.name)` registers the payload's
+`bin/` so mcpp can find the program by its bare name. A rule package should
+**name the program, not a path** — mcpp searches the `bin/` of every declared
+payload and then `PATH`, and can report exactly which directories it searched.
+
+**Libraries a consumer will link or load.**
+
+```lua
+exports = {
+    runtime = { libdirs = { "lib" } },
+},
+```
+
+`elfpatch` reads this from each dependency and writes the consumer's `RPATH`,
+which is what makes a stack of payloads resolve without anyone setting
+`LD_LIBRARY_PATH`.
+
+**Headers, so a compiler in this environment can build against it.**
+`sysroot.declare_libs(...)` and the header declaration place the payload into
+the SubOS sysroot view. **Declared rather than copied** — xlings removes them
+with the package, and a copy would outlive its owner.
+
+## The tier: when a payload is needed
+
+```toml
+"xim:qemu-arm" = { version = "9.2.4-1", when = "run" }
+```
+
+`when` is a second, independent gate beside the feature that selects the
+payload. The feature says **who** needs the tool; the tier says **when**. An
+emulator is needed to run and not to compile, so a CI job that builds firmware
+and never flashes it downloads nothing.
+
+## Current limitations
+
+- A payload is published to `xim-pkgindex`, which is a separate repository with
+  its own review; nothing in mcpp publishes one.
+- `latest` and "the highest version in the table" are two different questions,
+  and a consumer that wants the newest published version names `latest`.
+- A payload's own CI cannot verify that a consumer resolves it: that is what a
+  sandbox check against the published descriptor is for, and it is the only
+  thing that verifies the published bytes rather than the working tree.

docs/33-authoring-an-adapter.md

@@ -0,0 +1,92 @@
+# 33 — Authoring a Runtime Adapter
+
+**Reader:** someone making a library the **host** supplies reachable from an
+mcpp-built artifact on Linux — a graphics driver, a Vulkan ICD, a proprietary
+runtime.
+
+**The question this chapter answers:** why an artifact cannot see a library that
+is plainly installed on the machine, and what a package has to declare to fix
+it.
+
+**Not here:** packaging a library mcpp installs, which is
+[32 — Authoring a Payload](32-authoring-a-payload.md) and is the right answer
+whenever the library *can* be redistributed; and the runtime contract's fields,
+which are [04 — The mcpp.toml Manifest](04-mcpp-toml.md) §`[runtime]`.
+
+Before: [32 — Authoring a Payload](32-authoring-a-payload.md). After:
+[34 — Authoring a Board-Support Package](34-authoring-a-bsp.md).
+
+## The failure this exists for
+
+The library is installed. The loader finds its manifest. The `dlopen` fails
+anyway:
+
+```
+DRIVER: Found the following files: /usr/share/vulkan/icd.d/lvp_icd.json …
+ERROR:  libvulkan_lvp.so: cannot open shared object file
+```
+
+The libraries are in `/usr/lib/x86_64-linux-gnu`. What cannot reach them is the
+**process**: an mcpp-built binary runs under mcpp's own glibc, with its own
+search path,
+
+```
+interp: …/xpkgs/xim-x-glibc/2.39/lib64/ld-linux-x86-64.so.2
+rpath : …/xim-x-glibc/2.39/lib64:…/xim-x-gcc/…/lib64:$ORIGIN
+```
+
+so a bare-soname `dlopen` from inside that process does not search the host's
+library path at all. Nothing is broken; the artifact is simply not looking
+there, which is the property that makes an mcpp build reproducible in the first
+place.
+
+## What an adapter is
+
+**A symlink farm plus the metadata that makes it reachable.** Nothing is
+vendored, nothing is redistributed, and the package carries no upstream bytes.
+`runtime.library_dirs` puts a package-owned directory of symlinks on the
+artifact's runtime search path, and the chain resolves.
+
+A project declares the adapter as an ordinary dependency and does nothing else.
+
+## Why the driver itself is not a package
+
+A proprietary driver's userspace is in **ABI lockstep with a kernel module**,
+and its licence forbids redistribution. Neither is a packaging problem that
+effort solves, so such a driver is modelled as a **host capability** — something
+the machine either has or does not — and the adapter is how an artifact reaches
+it.
+
+An **open** driver is a different case and takes the other answer: it is a
+payload (`xim:mesa-lavapipe` for the CPU, `xim:mesa` for AMD hardware), and a
+machine using one needs nothing from the farm. Since 2026.09.05 an adapter also
+prefers the payload when one is published and its symbol set covers the host
+copy, so what the farm actually records is proprietary userspace and packaging
+backlog.
+
+## The three things an adapter gets wrong
+
+**The pattern list must cover transitive dependencies.** The whole chain has to
+resolve through the same directory. Mesa's software rasteriser pulls in LLVM;
+an NVIDIA driver pulls its own family. Listing the ICD alone produces the same
+`cannot open shared object file` one level down.
+
+**`libstdc++` belongs in the list, and it is not an oversight.** mcpp links
+libstdc++ **statically** — it is absent from a built binary's `NEEDED` — so a
+`dlopen`ed C++ driver has nothing to resolve against unless the host copy is
+provided here.
+
+**Nothing may be required.** A machine with no such driver at all is a
+legitimate configuration, and every CI runner in this ecosystem is one. The farm
+is then empty and the program reports what it actually found. An adapter that
+errors on a missing host library turns a supported configuration into a build
+failure.
+
+## Current limitations
+
+- **Linux only, by construction.** macOS's dyld and the Windows PE loader have
+  no equivalent layer, so a project targeting them declares no adapter.
+- An adapter cannot make a driver work that the machine does not have. It
+  removes one obstacle — reachability — and reports the rest as absence.
+- The farm's contents are decided when the adapter is installed. A driver
+  installed afterwards is not picked up until the adapter is reinstalled.