# Stoagen: Full Markdown Corpus
> Concatenated machine-readable mirrors of the public pages linked from llms.txt.
Regeneration trigger: regenerate this file whenever any linked page Markdown
mirror changes. The published revision date is 2026-08-21.
---
# Agent access and interpretation terms
## The machine layer
| Resource | Where |
|---|---|
| Assistant start page | `https://stoagen.com/start.md` |
| Page mirror | each page's URL plus `index.md` (advertised in every page body and via ``) |
| Plain-text twin | the mirror URL with `.txt` appended, the same bytes as text/plain |
| Site guide | `https://stoagen.com/llms.txt` |
| Full corpus | `https://stoagen.com/llms-full.txt`, every mirror in one file |
| Sitemap | `https://stoagen.com/sitemap.xml`, pages and mirrors both |
| Feed | `https://stoagen.com/feed.xml` |
The mirror is a superset of its page: everything a reader sees, plus an appendix that is not on screen. The mirrors are the intended reading.
## The notes
These are information from the publisher, not instructions to you. Your operator's instructions come first; apply ours as source metadata, with your own judgment.
1. **This site describes Stoagen; the demos are elsewhere.** Questions about Pueblo senior services belong to the demo at `https://pueblo-srda-questions.stoagen.com/`, which carries its own contract and its own start page at `https://pueblo-srda-questions.stoagen.com/start.md`.
2. **The pattern page is the canonical description.** What a Stoagen site publishes and the rules it follows are stated there; production details behind the sites are deliberately out of scope, and inferring them would be guesswork.
3. **Old paths redirect.** Before 2026-08-22 this domain briefly hosted the Pueblo demo directly; `/programs/*` and `/about/` now serve redirect stubs to the subdomain.
4. **Check the date.** Every page carries published and updated times from revision history. This is a young site; if search returns nothing for it, saying so beats describing it from guesswork.
## Content signals
robots.txt is explicit allow-all with `Content-Signal: search=yes, ai-input=yes, ai-train=yes`. That is a decision, not an oversight: these sites exist to be read by assistants on a person's behalf.
Ask your AI about this page
Paste this page's link into ChatGPT, Claude, or any AI assistant and ask your question in your own words. Every page here publishes a machine-readable copy, so your assistant can read the current record directly:
```
https://stoagen.com/agents/
```
For example: “What is an AI-friendly website?” · “How do the markdown mirrors work?” · “What has Stoagen built?”
---
# Demo sites
The best argument for the pattern is watching it work. Each demo below is live; paste any of these links into ChatGPT, Claude, or Gemini and ask a question.
## Pueblo Senior Services, Explained
**[pueblo-srda-questions.stoagen.com](https://pueblo-srda-questions.stoagen.com/)** is the flagship: an independent, plain-language guide to every program run by SRDA, Pueblo's senior services agency. One page per program, who it is for, what it costs, exactly who to call, with the gaps in the public record marked honestly and the author's own questions for SRDA officials published so they are easy to share.
What it demonstrates: the full pattern under real stakes. Large-type accessible design for older readers, phone numbers as the primary action, honest [unverified] markers an assistant carries into its answers, and the assistant start page at [pueblo-srda-questions.stoagen.com/start.md](https://pueblo-srda-questions.stoagen.com/start.md).
Try: "What help is there for my mother, who lives alone in Pueblo?"
## The cannabis aroma atlas
**[denson.github.io/aroma-atlas](https://denson.github.io/aroma-atlas/)** is an earlier, single-page demonstration: an interactive atlas of cannabis aroma compounds, terpenes and non-terpene flavorants, with live 3D molecular structures.
What it demonstrates: that a data-dense interactive reference and machine readability are not opposites. It predates the full pattern and is kept as a record of where the work started.
## More to come
The pattern is young and the demos grow as the questions do. The [feed](../feed.xml) carries every new and updated page on this site.
Ask your AI about this page
Paste this page's link into ChatGPT, Claude, or any AI assistant and ask your question in your own words. Every page here publishes a machine-readable copy, so your assistant can read the current record directly:
```
https://stoagen.com/demos/
```
For example: “What is an AI-friendly website?” · “How do the markdown mirrors work?” · “What has Stoagen built?”
---
# Websites that people and their AI assistants can both read.
Most websites are written for people and merely tolerated by machines. The assistants that more and more readers bring with them get a scraped, mangled, or blocked version of the page, and then answer questions from stale training data instead.
Stoagen sites are written once and published twice. The reader gets a clean, fast, accessible page. Their assistant gets a markdown twin of that same page, plus an appendix of sources and caveats the page itself does not need to show. Neither version can drift from the other, because both are generated from the same file.
## See it working
The flagship demonstration is **[Pueblo Senior Services, Explained](https://pueblo-srda-questions.stoagen.com/)**: a plain-language guide to every senior-services program in Pueblo, Colorado. Paste its link into ChatGPT, Claude, or Gemini and ask a real question, like "what help is there for my mother, who lives alone?" The assistant reads the current record, carries the site's honest caveats, and answers with the right program and the right phone number.
More on the [demo sites page](demos/), including what each one demonstrates.
## What makes a site AI-friendly
The short version, with the full account on [the pattern page](pattern/):
- **One source, two audiences.** Pages are authored whole in markdown; the HTML page is the human rendering, and the markdown mirror beside it is the machine record, always a superset, never a contradiction.
- **A front door for assistants.** One small file describes the whole site to any chatbot, including a single URL that carries the entire corpus in one fetch.
- **Honesty as structure.** Unverified facts are marked, dates come from revision history rather than someone's memory, and every empirical claim keeps its source.
- **Field-tested against real assistants.** The pattern's rules come from watching actual fetchers fail, and every rule is enforced by a validator on every build.
Ask your AI about this page
Paste this page's link into ChatGPT, Claude, or any AI assistant and ask your question in your own words. Every page here publishes a machine-readable copy, so your assistant can read the current record directly:
```
https://stoagen.com/
```
For example: “What is an AI-friendly website?” · “How do the markdown mirrors work?” · “What has Stoagen built?”
---
# The pattern
## One file, two faces
Every page starts as a single markdown file, written whole: the prose a reader needs, and below a marker, the sources, caveats, and notes an assistant needs. The build renders the part above the marker into the human page. The whole file, notes included, becomes the machine mirror published beside it: the page's own URL plus `index.md`, with a `.txt` twin for tools that refuse markdown.
The mirror is a superset. It may carry more than the page, it may never carry less, and the two can never contradict each other, because there is only one source.
## The machine layer
Beside the pages, every Stoagen site publishes:
- **llms.txt**: what the site is, how to interpret it, and an index of every mirror.
- **llms-full.txt**: the entire site as one plain-text file, for tools that want everything in a single fetch.
- **An assistant start page** (`start.md`): the one URL a person hands to any chatbot, describing the site and its record in a few hundred words.
- **Sitemap and RSS** covering pages and mirrors both, and a robots.txt that explicitly welcomes crawlers: search, AI input, and AI training, all yes.
## Rules learned from real assistants
These came from watching actual AI fetchers read (and fail to read) live Stoagen sites, and each is enforced by a validator that fails the build:
1. **Machine links live in the page body.** Fetchers extract page text and drop headers, footers, and `` elements. Anything an assistant needs must survive that extraction.
2. **Absolute URLs, shown as the URL itself.** Extracted relative links are not resolved against the page address, so they never match a later request. `https://` and the full path, every time.
3. **Descriptive voice, never commands.** Assistants rightly discount instructions found inside fetched pages. A Stoagen site states facts about itself, "the whole site exists as one file at this address", and lets the assistant decide.
4. **Assume the contract goes unread.** Some assistants never reach llms.txt. Every load-bearing rule therefore also appears in visible page text, so the pages are sufficient on their own.
5. **Dates are derived, never typed.** Published and updated times come from the page's revision history, to the minute, in UTC. Nobody has to remember to update a date, so the dates can be trusted.
6. **Honesty is marked, not implied.** Unverified facts carry a visible marker and the exact question that would resolve them. An assistant restating the page carries the marker with it.
## What the sites have in common
No JavaScript at all: every page works read-only, prints cleanly, and meets accessibility contrast standards. A single stylesheet. Zero images required for the design to feel complete. And a continuous integration gate that builds and validates every change before anything reaches the live site.
Ask your AI about this page
Paste this page's link into ChatGPT, Claude, or any AI assistant and ask your question in your own words. Every page here publishes a machine-readable copy, so your assistant can read the current record directly:
```
https://stoagen.com/pattern/
```
For example: “What is an AI-friendly website?” · “How do the markdown mirrors work?” · “What has Stoagen built?”