In the last post I showed you a machine paying ten dollars to walk into my museum. Real money, real chain, a credential issued and a door opened with nobody standing at it. I was pleased with myself for about a day. Then I went looking for the thing I had built, the way an agent would look for it, and I could not find it. Not because it was broken. Everything worked. It worked perfectly for anybody who already knew the exact address, the exact endpoint, and the exact order to ask for things in. Which is to say it worked for me, and for nobody and nothing else in the world.
I have been here before. I have twenty nine thousand pieces of my own work in an archive, and for most of my life a good half of them may as well have not existed, because they were on a dead drive, in a folder I could not name, on a platform that closed. Making a thing and making a thing findable are two different jobs. I keep learning this. Apparently I keep needing to.. still..
A door nobody can see
Here is the situation in plain terms. If you are a person, you find my museum because you land on my site, you see a link, you click it. Your eyes do an enormous amount of work you never think about. An agent has no eyes and does not browse. It reads a small number of specific files, and if the thing you are selling is not written in one of them, then as far as every machine on the internet is concerned, you are not selling it. There are four of these files and almost nobody talks about them. The first is llms.txt, a plain text file sitting at the root of a website, written for machines to read the way robots.txt was written for crawlers. Mine describes the whole catalog. It did not mention the museum pass..
The second is an ai-plugin manifest, which tells an agent in one paragraph what this site can do for it. The third is an OpenAPI specification, which is the actual instruction manual. Every endpoint, every parameter, every response. If it is not in here, an agent has to guess, and agents do not guess.The fourth is an agent card, which is what agent registries read when they are cataloguing what exists in the world. This is the one I got wrong, and I will come back to that.
The museum was in none of them.
What I actually did
I wrote the pass into all four.
llms.txt now carries a section that names the three tiers, prints their real prices and their real product numbers, and walks through buying and entering in three steps. The product numbers are pulled live from the store rather than typed in, so the file cannot drift away from what is actually for sale. That mattered to me more than it sounds like it should. A document that can go quietly stale is worse than no document.
The manifest names the pass. The OpenAPI spec documents all three endpoints with their responses, including the 402 you get when you have no pass, which carries the address of where to buy one, so an agent that arrives at a locked door can work out how to open it without a human.
And the agent card now lists Enter the museum as a skill, alongside browsing the catalog and getting a crypto quote.
That last one took me two tries, which I will get to.
The part I am most pleased with
My commerce plugin is two thousand six hundred lines long. It serves the catalog, the payment quotes, all four of those discovery files, and it is the thing standing between my storefront and a white screen. A mistake in there takes the whole shop down. The obvious move was to open it up and paste the museum into it. I did not do that. Instead the file got seven single lines added, and nothing else. Each one is a hook that says: anybody else may add to this document. All the actual museum writing lives in a separate plugin, which can be switched off, rewritten, or thrown away entirely without that big fragile file ever being touched again. Seven lines, and the two things stopped depending on each other. I keep finding that this is not really a coding idea at all. It is closer to how I have learned to work on anything. When something is already holding weight, I try not to cut into it. I would rather give it somewhere to be added to from the outside, and build the new thing there, where I can break it without breaking anything that matters.
What went wrong, because that is always the useful part
I put the museum skill in the wrong document. I added it to the ai-plugin manifest, which felt right, and then went to check and found the manifest has no skills section at all. Skills live on the agent card. Two documents that look similar, doing different jobs, read by different things. I had assumed instead of looking. Then I tested whether hiding the agent passes from my human shop had worked, and I nearly reported the wrong answer twice in a row. The first test searched my site and found the pass, so I thought the hiding had failed. It had not. A search results page prints your search term back at you, so the words were on the page whether or not there was a result. I was reading my own question and calling it an answer.
The second test looked at my shop page and found nothing, which seemed like success. Then I checked whether my test could find a product I knew was there, and it could not find that either. The test was broken. It would have said success no matter what. Both times the fix was the same. Test something you already know the answer to, first. If your test cannot see a thing that is definitely there, your test is not telling you anything, and a green result is the most dangerous kind of wrong. I also found that my site was sending a security header that quietly contradicted another one, in a way that would have made the museum unreadable to any agent running inside a browser. That took ten seconds to fix and would have taken a very long time to notice.
What this is really about
I have spent years turning fragments into an archive, and the last two turning that archive into something that can answer for itself. Every one of those steps was the same step. Take a thing that exists but cannot be reached, and make it reachable. A museum an agent cannot find is a drive in a drawer. It is the work in the folder I could not name. It is every piece I made and lost. The technology is new and the problem is not new at all, and I find that oddly comforting. The door is open now, and it is written down where machines look.
If you have an archive, a shop, a practice, anything at all sitting behind a door nobody can see, I would genuinely like to talk about it. That is the interesting part now. More to come.
