6.4 Colophon: Dogfooding MAGE
A colophon is the note a book keeps about its own making — traditionally set near the end, where the typeface, the press, and the hands that set the type are recorded.
6.4.1 The production, briefly
This book was set in Fraunces for display, Source Sans 3 for the body, and IBM Plex Mono for code, on a warm paper stock with a single burnt umber accent. There was no separate typesetting pass. The manuscript is one structured source — chapters, sections, figures, and citations — that a single build script projects two ways book/build_book_html.py: to HTML for the web edition, and to Typst for the print PDF, which typst then lays out. The web book and the print book are two views of one source, so they cannot drift apart. The whole thing is kept under version control, validated and built by one stdlib-only tool that runs on a fresh checkout catalog.py. References live in a BibTeX file book/references.bib, resolved through inline markers, with a gate that refuses to build on a stale citation. The figures are hand-drawn SVGs — no plotting library behind them — each carrying a title and a description for readers arriving by screen reader.
Those are the facts a colophon usually records. The more unusual one is that the book was maintained using the method it describes.
6.4.2 The manuscript became an engineered system
The argument no longer lived solely in prose. It lived in explicit models that could be inspected, evolved, and kept consistent as the manuscript changed. Alongside the chapters sat a small set of structured models — the book's case written out as data, its concepts named, its claims registered, its citations positioned — and a build step that held those models in agreement with the prose the same way the rest of the method holds things together.
This was not an accident of tooling. Earlier, the book argues that MAGE is not fundamentally a software methodology but a method for governing large evolving artifacts through explicit models and executable constraints — the general claim Table 6.0-4 frames as a prediction for the next study to test. The manuscript became a chance to test that claim directly. The artifact under construction was no longer software. It was a technical argument — a book — and the same discipline governed it.
6.4.3 The models that governed it
Each model carried one facet of the manuscript's structure, and a check held that facet consistent as the prose moved. Table 6.4-1 names each one with the failure it prevented. They are described here in the book's own vocabulary — explicit models, traceability, drift, synchronization, governance — because the point is recognition: this is the same method the preceding chapters taught, turned on the book itself.
| Model | Purpose | Prevented failure |
|---|---|---|
| Argument-spine model | The book's case as an ordered run of numbered claims, with which chapters advance each | A claim advanced nowhere, duplicated across chapters, or spread thinner than it is taught |
| Chapter-shape model | Each chapter's opening and closing graded against the editorial discipline | Structural drift — an opening that never names the failure, a closing that only restates |
| Concept-and-vocabulary map | One canonical phrase for each of the book's central ideas | Terminology drift — the settled structured model slipping back toward typed model |
| Claims model | The load-bearing propositions, each with an audit predicate naming the prose that would negate it | An unsupported claim, or one the later text quietly contradicts |
| Literature-positioning model | One record per intervention, each carrying its established-lineage → current-frontier → narrow-move frame | A citation floating loose, or the book mis-positioned against neighboring work |
| Substantiation ledger | Each factual number bound to the claim it backs, its source, and its limit | A claim about the world with no data and no literature behind it |
| Flagship-case model | The case studies as packages of catalogue entries, one row per architectural part | A case-study description drifting away from the catalogue it draws on |
| Design tokens | One source for the faces, the accent, and the type scale, projected to every output | Visual drift between the web edition and the print edition |
None of this is the book; the prose is the book. The models gave the argument somewhere outside the prose to live, so a change in one place could be traced to its consequences in the others.
That traceability paid off most when a claim moved. Because the argument existed as an explicit model, a global inconsistency became visible at once instead of surfacing by accident during editing. Three architecture-view chapters were labeled in the spine as advancing both of the book's theses; a sensor that watches for a thesis spread across more chapters than it is genuinely taught in flagged the second thesis and named exactly the three chapters responsible. The fix was small, and the model made its reach exact — a bounded worklist of three openings to re-read, rather than a whole-book hunt. The machinery did not decide what the change should be. It made the reach of the change finite and visible, which is the smaller and more useful thing.
6.4.4 MAGE, applied outside software
Running the method on the manuscript followed the same loop the book teaches for code:
- Ideas arrived first, usually as speech in the author's own cadence.
- Explicit models captured the structure the ideas belonged to — the spine, the claims, the concepts.
- A governed manuscript held the prose and those models together under one build.
- AI drafting turned rough material into candidate text to argue with.
- Consistency checks flagged where a model and its prose had fallen out of agreement.
- Human judgment decided every revision, and rewrote every sentence into the author's voice.
- A finished manuscript emerged that a check could confirm was internally consistent.
The governed manuscript sat under the same declared-source-plus-generated-artifact shape the rest of the method uses, laid out in Table 6.4-2: a human authors the model, a build maintains its derived forms, and a drift check refuses to let the two disagree.
| Model | Human authored | Machine maintained | Drift checked |
|---|---|---|---|
| Argument-spine model | Declared claims and per-chapter labels | Generated spine and summaries | ✓ over-spread sensor |
| Chapter-shape model | Per-chapter opening/closing assessments | Derived reports | ✓ |
| Claims model | Declared propositions and audit predicates | Generated claims register | ✓ |
| Literature-positioning model | Declared interventions and frames | Generated positioning artifact | ✓ |
| Substantiation ledger | Data bindings, by hand | Aggregated per-claim backing reports | ✓ under-substantiation query |
| Design tokens | Declared faces, accent, and scale | Projected CSS, Typst, and SVG palette | ✓ token-drift lint |
Because structured models absorbed the structure, the manuscript could take repeated large-scale rewrites without collapsing into inconsistency. That is the workflow the earlier chapters describe for a codebase, run on a book — the same loop the theory draws for code in Figure 6.0-1, now shown to scale past software to any artifact whose internal consistency has to hold.
6.4.5 What the language models did
Large language models were part of making this book, and it would be coy not to say so. They helped find adjacent research, proposed candidate citations, compared the argument against neighboring work, drafted figure concepts and accessible descriptions, and turned rough material into drafts worth arguing with. The lasting lessons are engineering ones, not the fact of the tool:
- AI accelerated exploration — it surfaced where a literature already existed and turned thought into candidate prose quickly.
- Structured models constrained that exploration — the spine, the claims, and the concept map kept generated text answerable to a declared shape.
- Human judgment owned the architecture — the argument, the evidence, and every acceptance or refusal of a revision stayed on the human side.
- Every factual claim was independently verified — a model will produce plausible bibliographic detail that is wrong, so every citation, quotation, and number was checked against its primary source before it was allowed to stay.
6.4.6 Limits, and human judgment
The machinery had a firm boundary, and it is worth stating without hedging. It could trace a claim through the book; it could not decide whether the claim was true. It could hold two representations in agreement; it could not turn that agreement into correctness. A consistency check can show that the model and the prose agree. It cannot show that either is right.
The method reached the manuscript's models, its structure, and its drafting. It did not supply the voice. Writing for other people is human-to-human communication, and voice is part of the message — so every sentence was rewritten by hand, and the judgments that mattered stayed human: choosing the argument, deciding what counted as evidence and where the evidence stopped, judging when a claim had grown too strong, and standing behind the finished book. The models made those judgments easier to carry across hundreds of pages. They did not make them.
Earlier, the book argued that MAGE governs complex evolving artifacts through explicit models and executable mechanisms, and that the claim was not confined to code. This manuscript became the first non-software artifact developed under that method. The software system described in these pages was built with MAGE. The book describing that system was, in turn, written with MAGE — which is the book's larger claim made concrete: MAGE is not merely a software engineering methodology, but a method for engineering any sufficiently complex artifact whose internal consistency matters.