The folder
Every modernization project we’ve seen starts the same way: with a folder. Inside it, a database dump someone exported in a hurry. Forty screenshots of the old system, taken because nobody could find the manual. An Excel file the whole company secretly runs on. A Word document titled “Requirements v2 FINAL” that was last edited nine years ago and is wrong in ways only one employee knows.
The instinct is to treat this folder as debris, the sad leftovers of the thing you’re replacing. Clean it up later. Start fresh.
We think that instinct is exactly backwards. That folder is the spec. It’s the only document that describes what the business actually does, as opposed to what someone once hoped it would do, and it was written the only way reliable specifications ever get written: by a system running in production for years, in front of users who complained when it was wrong.
In Sapilon, the files in that folder are called artifacts, and how we handle them is one of the more deliberate decisions in the product.
Nobody wrote the requirements. The old system did.
Ask a team for the requirements of their legacy system and you’ll get a shrug. Ask for the database and you’ll get 60 tables where every column is a decision someone once made for a reason: the status field with eleven values because the business really does have eleven states, the nullable approved_by because approval was bolted on in year three, the notes column holding half the company’s institutional memory.
Screenshots carry the same weight. That cramped list view with the odd filter in the corner isn’t bad design to be swept away. It’s a record of what people needed to see every morning to do their jobs. The Excel export is the data model users built themselves when the system wouldn’t bend.
None of this is written down anywhere else. If a rebuild ignores it, users will spend the first six months of the new system filing tickets to put it all back.
The two wrong ways to use these files
Once you accept that the folder matters, the question becomes how an AI agent should use it. The industry has settled on two answers, and both are wrong.
The first is to paste everything into the model’s context, every time. It feels thorough, and it fails in a way nobody notices. Shove a 4,000-line SQL dump, a stack of screenshots, and three Word docs into every request, and the request where you asked for a button color change now carries your entire legacy system along for the ride. Cost goes up, and, less obviously, quality goes down, because a model wading through everything is worse at finding the one thing that matters. Attention is a budget, and this spends it on noise.
The second answer is to summarize: analyze each file once, keep a sentence about it, discard the rest. This is what most tools actually do, and it produces a specific kind of failure that’s easy to miss in a demo. Ask the agent to build a task form from your uploaded schema and it knows that a tasks table exists; the summary said so. It does not know the columns, the types, or what points at what, because a summary is exactly the thing that threw that away. So it guesses. The form looks plausible, matches nothing, and you find out at data-migration time.
A summary is an index. You cannot build from an index.
Know everything, read what’s needed
Sapilon’s answer is to stop choosing between the two and give each half its proper job.
The agent always carries a catalog of the project’s artifacts: a compact map of what exists and what each file contains. Not the files themselves; the knowledge that they’re there. schema.sql, seven tables, here are their names. dashboard.png, the old task list, this navigation. spec.md, four sections. This map is small enough to be present in every conversation, so the agent is never unaware of what it has.
When a task actually calls for one of those files, the agent reads it: that specific file, in full, at that moment. Building the task form pulls the schema. Recreating a screen pulls the screenshot. Fixing a typo pulls nothing at all. The judgment about what’s relevant is made per task, by the same intelligence doing the task, which turns out to be a much better relevance filter than any similarity search bolted on beside it.
And when the agent reads a file, it reads it as what it is. A database dump isn’t a wall of text to skim; it’s parsed into tables, columns, types, and the relationships between them, which is the form you’d want it in if you were doing the work yourself. A screenshot is looked at as an image, labels and layout and all. A spreadsheet is columns plus enough real rows to understand the shape of the data. A Word spec is its sections. Each kind of file gets read the way a careful engineer would read it, because “convert everything to text and hope” is how nuance dies.
One more thing falls out of this design almost for free: provenance. Because every read is an explicit, logged action, the project keeps a record of what was consulted for what. When the task form exists, you can see it was built from schema.sql, not from a guess. On a system that will hold real data, “where did this come from” should never be a mystery.
Truth has a lifecycle
There’s a subtlety we care about, because getting it wrong causes real damage. Early in a project, when nothing has been built yet, the artifacts are the truth: the uploaded schema is the data model, the screenshots are the screens. The agent treats them as authoritative, because there’s nothing else to be authoritative.
But the moment real code exists, the roles must flip. The live schema in the codebase becomes the source of truth, and the artifacts become what they always should have been: the spec to check the work against. An agent that keeps treating a year-old SQL dump as gospel after the real database has moved on will happily “fix” your production schema back to 2019. Sapilon tells the agent, explicitly, which regime it’s in.
Files don’t change when this happens. Their authority does. Respecting that distinction is most of what “using legacy artifacts well” actually means.
Bring the folder
The rest of Sapilon is built on the belief that software is a lifecycle, not a prompt. The artifacts philosophy is the same belief pointed backwards: your project doesn’t begin at the first prompt either. It began years ago, in a system that worked well enough to be worth replacing, and the evidence of everything it learned is sitting in a folder someone almost deleted.
So don’t start clean. Start honest. Bring the dump, the screenshots, the spreadsheet, the Word doc that’s wrong in instructive ways. The old system spent a decade writing your spec. The least the new one can do is read it.