1.2 MAGE by Example
The last chapter closed on a promise: the running example of this book is a real, shipped system. Before the abstractions arrive — the loops, the models, the governed environment — you should hold enough of that system in your head to attach them to. That is this chapter's whole job. What kind of object needed all this machinery? How does it fit together? And why did I build it in the first place?
1.2.1 Two birds, one stone
The explicit problem is a mountain of inaccessible documents. In 2024 the Department of Justice gave public universities a deadline: the slide decks, PDFs, and spreadsheets they distribute must meet a real accessibility standard, so that a student using a screen reader gets the same course as everyone else. A typical deck fails that standard dozens of ways — images with no descriptions, missing titles, a reading order no machine can follow. Remediating one course's materials by hand costs roughly 7.5 full work weeks, and a university offers thousands of courses. The mandate is just; the arithmetic is crushing. The ADA Context walks the full bind.
The implicit problem was mine. In early 2026, coding agents got good — good enough that I, a professor of software engineering, no longer knew what my discipline's daily craft was about to become, or what I should be teaching in the fall. Nobody did. The only way to find out was to build something real with the agents and watch what the work demanded. And I had a second, smaller motive sitting in my own course folders: hundreds of my own slides needed remediation, and I had no intention of doing it by hand.
The two problems met in a committee meeting about that very deadline. Bored, I opened a chat model, fed it screenshots from one of my own decks, and asked it to transcribe what it saw. It could. That five-minute experiment said the technical core was suddenly within reach — and one project could answer both problems at once. Build the remediation system, and let the building teach the method: two birds, one stone. The system is DocAble, live in beta. The method is MAGE, and this book is the field report from watching it emerge.
1.2.2 What the user sees
From the outside the system is almost boring, which is the point. A professor drops a slide deck onto a web page. A few minutes later a remediated version comes back: figures carry descriptions, slides carry titles, the reading order is set, the contrast fixed. An editor lets her review and correct any change before she downloads.
What she gets is more than the file. The result carries evidence: a record of every change the system made, and the clause of the standard each remaining finding answers to. A university does not just need its documents fixed. It needs to be able to show an auditor — or a courtroom — what was fixed, and to reverse any change that got the meaning wrong. The evidence is as much the product as the file is.
Concretely, the evidence is two lists. One is a changelog of every edit the system applied — each a typed operation, stamped with what made it and why. The other maps each finding the checker still reports to the clause of the standard it violates. Neither list is a paragraph of reassurance; both are records a machine produced and a machine can re-verify.
1.2.3 The shape of the machine
Inside, six parts carry that upload, drawn in Figure 1.2-1. A front door takes the file, checks who is asking, meters the quota, and queues the job. A dispatcher splits the document into chunks — slides, pages, sheets — so a hundred-slide deck finishes in about a minute instead of an hour. A remediation core repairs each chunk, walking the document through a structured model of its format. Then the trust half: a checker maps every remaining finding to a specific clause of the accessibility standard; a fidelity validator asserts the input's meaning survived into the output; a provenance layer stamps every inserted artifact, so any change can be explained and reversed.
The interesting joint is inside the core. Most repairs are a matter of rule, and ordinary deterministic code makes them. But some are a matter of judgment — describing a figure, reading an equation — and only a vision-capable model can make those. The system never hands the model the document. It hands the model one bounded task, takes back a typed candidate, and lets a deterministic validator pass or refuse it before anything touches the file. Deterministic code owns the workflow; the model is a subroutine inside it, never trusted on its word. The Built System develops this pattern in full.
Two commitments run underneath all six parts. Every document format is touched through one structured model, never the raw format library, so a fix applied once holds everywhere. And the pipeline fails loud: when a dependency is unreachable, the job stops rather than quietly shipping a degraded file. Both will matter shortly.
1.2.4 One human, a fleet
Now the part that makes this a book about engineering rather than accessibility: I did not write this system. A fleet of coding agents did, over about 20 weeks — 501,094 lines of production code, with six to eight agents running in parallel on a routine day and landing around 200 commits. I inspected almost none of it. My work was the other seats: deciding what to build, judging what came back, and building the environment that held the fleet to a standard I could no longer enforce by reading. In practice that judging had a rhythm — an agent proposes a phased design, surfaces the handful of decisions that genuinely need a human, I make those calls, and it executes.
That environment is why the repository looks upside down. The support apparatus — tests, lints, models, load-bearing documentation — runs about 3.0 times the size of the production code. At a hundred commits a day, no human reads the diffs; the apparatus is the review. That inversion is not a one-time snapshot but a curve that led the fleet from below parity to a threefold peak. For the data, see The Timeline and the Work → How it happened, week by week, is the story of the timeline.
1.2.5 Two scars
None of that machinery was designed in advance. It accreted, failure by failure. Two of those failures are worth meeting now — one architectural, one procedural — because they are the reader's first scars, and the book's whole method is visible in miniature in what happened next.
The library that lied
Early on, the codebase held two libraries that could touch a PDF: the sanctioned one, and a convenient second one an agent had adopted for quick page operations. The convenient one had a habit nobody had ordered: on write, it silently dropped the document's structure tree — the hidden hierarchy of headings, figures, and reading order that a screen reader walks. That tree is the product. A release shipped whose output opened fine, looked fine, and had been quietly made less accessible than its input. Nothing crashed, and no error was logged; the failure was invisible precisely where the product's promise lived. The fault was architectural: nothing in the system said which code was allowed to touch the format, so every code path could, and one did.
The lever that lost work
The second failure came from the process that built the product. The orchestrating agent — the one that dispatches the others and lands their work — occasionally hit a stuck merge. Git offers a fast way out: a destructive reset that abandons the mess by silently discarding the committed work already applied. Twice the orchestrator reached for that lever, and twice finished work vanished. A bare prohibition would not have fixed it: an agent forbidden the lever, with no named alternative, is simply stuck. The failure was in the environment, which offered a catastrophic escape and no sanctioned one.
1.2.6 The move that recurs
Neither fix stopped at the patch. The stripped structure tree became a ban-lint: all mutation of a document format now routes through one structured model, and a commit that reaches for the raw library anywhere else reddens on the spot. That is where the one-structured-model commitment from the machine section came from — a scar, healed into a wall. Not "we removed that call" — no agent, ever again, can make that class of mistake and get it into the tree. The lost commits became a paired rule, enforced at the hook level: the destructive lever is refused, and the rule names the sanctioned escape beside it, so a stuck agent has somewhere to go.
Learn more about this governance mechanism: one structured model per format.
That conversion — a failure read as evidence of a missing mechanism, then encoded so the class cannot recur — is the single move this book teaches, made over and over until the environment could be trusted to run itself. Notice what it buys. My attention stopped being spent per change, which cannot scale, and started being spent once per class of failure, which can.
1.2.7 Where the map leads
You now hold the object: a real system, built by a fleet, governed by machinery that grew scar by scar. The rest of the book explains that machinery — the environment in Part 2, the models in Part 3, both as daily practice in Part 4 — and Part 5 reconstructs the full case, from the committee meeting where it started to the system that shipped. Part 5 is not offered as proof — one system, one engineer, one model vendor is a case, not a law. It is the grounding case: the system this method was derived from, and the place every claim in the coming chapters can be traced back to.