What "agent-readable" actually means

"Agent-readable presence" is a terrible phrase to say to a barber, and we say it anyway because we haven't found a better one. It sounds like a black box — some AI thing that happens to your business behind a login. So when someone asks what it actually is, we've started answering the boring, honest way: it's a few text files with your business facts in them, written in a shape a machine can read. Then we show them the files, because the files are the least intimidating part.

Let's do that here. Three artifacts, plain language, no login.

llms.txt is a text file with your hours in it

The first one is called llms.txt. It's an emerging convention — a plain-text (well, Markdown) file you put at the root of a site, meant to give an AI assistant a clean summary instead of making it scrape a pile of HTML. Think robots.txt, but for describing yourself rather than restricting crawlers.

Here's roughly what one looks like for a made-up barbershop — close to what Lodestar generates for a business:

# North Hill Barbers

> A neighborhood barbershop — skin fades, beard trims, and hot-towel
> shaves. Walk-ins welcome; booking recommended on weekends.

- [Full profile](https://north-hill-barbers.lodestars.app/llms-full.txt)
- [Structured data (JSON-LD)](https://north-hill-barbers.lodestars.app/profile.jsonld)
- [Agent endpoints](https://north-hill-barbers.lodestars.app/.well-known/agent.json)

Category: Barbershop

## Services
- Skin fade — $35 (45 min)
- Beard trim — $20 (20 min)
- Hot-towel shave — $40 (30 min)

## Hours
- Tuesday: 9:00 AM – 6:00 PM
- Saturday: 9:00 AM – 4:00 PM
- Sunday: Closed

## Contact
Phone: (555) 555-0132

That's the whole idea. A title, a one-line summary in a blockquote, links to more detail, and then the facts a customer actually asks about — services with prices, hours, how to reach you. Nothing here is proprietary or clever. You could write this in a text editor in ten minutes, and honestly, for a single business, you should be able to.

JSON-LD is the same facts, labeled for machines

The second artifact is JSON-LD — "JSON for Linked Data," which is a mouthful for "the same facts, tagged so software knows which is which." It uses schema.org, the shared vocabulary Google has used for years to build those rich business cards in search results. Assistants read it for the same reason: it removes the guesswork about whether "9–6" is your hours or your prices.

Trimmed down, the barbershop's looks like this:

{
  "@context": "https://schema.org",
  "@type": "LocalBusiness",
  "name": "North Hill Barbers",
  "url": "https://north-hill-barbers.lodestars.app",
  "telephone": "(555) 555-0132",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "12 North Hill Road",
    "addressLocality": "Portland",
    "addressRegion": "OR"
  },
  "openingHoursSpecification": [
    { "@type": "OpeningHoursSpecification",
      "dayOfWeek": "Saturday", "opens": "09:00", "closes": "16:00" }
  ]
}

Same information as the llms.txt, wearing name tags. The real file is a bit longer — it wraps this LocalBusiness together with your service list (as an OfferCatalog) and your FAQs (as a FAQPage) in one graph — but the shape is exactly this: a fact, and a label saying what kind of fact it is. If you've ever added schema.org markup for Google, you already know this one. It isn't new; the audience for it is.

The /.well-known door, and the live one

The third file lives at a boring, predictable path: /.well-known/agent.json. The /.well-known/ folder is a standard corner of a website — a known place to leave machine-facing documents so software doesn't have to hunt. Ours is a small discovery doc: it tells an agent "here's this business, and here are the other things you can read or connect to."

One of the things it points at is the part that isn't a file at all: a live endpoint an agent can connect to and ask questions, rather than a static snapshot it downloads. That's the MCP server — the "active surface" — and it's genuinely a different animal, enough that it's its own post. For today the useful distinction is just this: the first two artifacts are a photograph of your facts; the endpoint is a phone line.

One form, three files, kept in agreement

Here's the honest problem, and it's not the writing. Any one of these is easy to make. Keeping all of them — plus your actual website, plus your Google listing — saying the same thing after you raise the fade price or change your Sunday hours is where it quietly rots. You update one, forget the other three, and now a machine is confidently telling customers last year's price. The stale fact is worse than no fact, because someone acts on it.

That sync problem is most of what we're building Lodestar to handle: you edit the facts once, and the llms.txt, the JSON-LD, the discovery doc, and the live endpoint all stay in agreement. But we want to be straight about it — the files themselves aren't the product. They're open conventions. The product is not having to remember four places.

Write one yourself

If you take one thing from this, take the skeleton. For any site you run, you can publish an /llms.txt today:

• An # H1 with the name.
• A one-line > summary of what you do and who for.
• Sections for the handful of facts people ask about — what you offer, hours, where, how to reach you.
• Links to anything longer.

That's it. Whether you hand-write it or a tool keeps it in sync, the bar is the same, and it's low: your real facts, legible to a machine, kept current. The acronyms are just the file names.