Point an AI coding agent at a legacy ERP cold and it will do the thing models do when they do not know the system: guess, fluently. It will invent a plausible view name, assume a write works like the matching read, and hand you confident code that fails against the real thing. The ERP behind this portal has 2,814 SQL views and 52,041 columns and a write API split across 10 modules. There is a lot of room to guess wrong. This is a teardown of the map I built so the agent works from the truth instead, and the audit that proved the map needed a second layer.
The base layer is mechanical and not very interesting on its own. A regeneration script reads the live database schema and the cached API specs and compiles a reference: 36 module files covering the views, the columns, the write endpoints. Because it is generated from the live system, it reflects the database as it actually is, not as someone remembered it during onboarding two years ago.
The layer that earns its keep is the cross-reference. Raw schema tells you a column exists. It does not tell you which column answers a business question, and that gap is exactly where an agent guesses. So the reference carries tables that map a business concept to where you read it and where you write it: read this concept from this view, write it through this endpoint. That bridge is the knowledge that normally lives only in the head of whoever has worked the system longest. Writing it down where the agent can read it is the difference between correct work and plausible work, and it falls naturally out of how the portal is built, reads from views, writes through the API.
Then there is the second ERP-adjacent surface, a construction-cloud platform API, and that one taught me the harder lesson. Its reference covers 16 API families across seven cached specs. Six of those families I verified by actually calling them against the live account. The rest I documented from specs and inference. And a reference that mixes verified facts with educated guesses, in the same confident tone, is worse than no reference, because the agent cannot tell which lines to trust.
So every claim carries a provenance tag. PROBED means I called it and saw the result. DOC means it came from the vendor's documentation. INFERRED means it is my best read of the surrounding shape. The tag is not decoration. It tells the agent, and me, how much weight a line can bear.
That tagging is what made the next step possible. I ran an adversarial audit against the construction-cloud reference, deliberately trying to break its claims, and it flagged 16 wrong and 11 suspect entries. They clustered on write endpoints, which is the most dangerous place to be confidently wrong. Writes on that platform are shaped differently from reads, so a write claim copied from a read pattern was frequently false. The corrections now live in a curated block on each page, and the agent is told to trust that block first. I could only aim the audit because the provenance tags already told me which claims were guesses.
A map generated from a live system goes stale the moment the system changes, and a stale map that still reads as authoritative is its own trap. So a scheduled drift detector compares the compiled reference against the live schema and surfaces divergence before a release trips over it. The map is maintained, not carved once.
If you want an agent to work safely against a system you do not control, the highest-value thing you can build is not a cleverer agent. It is a map of the system that is generated from ground truth, organized around the questions the work actually asks, honest about the line between what you verified and what you assumed, and checked for drift. The audit catching 16 bad write claims before any of them reached the live account is the whole argument: those would have been silent failures against a real company's data, and the map is what stopped them.
Building that grounding layer is most of the work in putting an AI agent to work against the messy systems a real business already runs on. I do that as an embedded engineer, in the client's cloud, on the client's data. If your agent is guessing at a system it does not understand, the fix is a map, and that is a good conversation to start at /services.