Problem
https://archon.diy/llms.txt and /llms-full.txt both return 404; the Starlight site at packages/docs-web/ has no llms.txt plugin configured.- Experienced by anyone pointing an AI tool (Cursor, Claude projects, ChatGPT retrieval) at the Archon docs — they must scrape HTML, clone the repo, or paste pages manually.
- Comes up every time a user asks their LLM about workflow authoring, node types, config, or variable substitution and gets stale or hallucinated answers.
- Particularly acute here because Archon's audience is, by definition, LLM-assisted developers.
Proposed Solution
Add starlight-llms-txt as a dev dependency of @archon/docs-web. The plugin reads existing markdown under src/content/docs/ and generates three endpoints at build time:
/llms.txt — index of all doc pages with titles and descriptions (llmstxt.org spec)/llms-full.txt — full markdown concatenation of all docs/llms-small.txt — trimmed variant
Implementation touches two places:
packages/docs-web/package.json — add starlight-llms-txt to devDependenciespackages/docs-web/astro.config.mjs — import the plugin and add it to the plugins: array in the starlight() config
User Flow
Before (current)
User asks LLM: "How do I author a DAG workflow in Archon?"
[!] LLM has no training data on Archon
[!] User has to paste docs manually or accept hallucinated answers
After (proposed)
User: "Use https://archon.diy/llms-full.txt as context"
[+] LLM fetches concatenated docs
[+] Accurate, current answers grounded in the real docs
Alternatives Considered
| Alternative |
Pros |
Cons |
Why not chosen |
| Do nothing |
Zero work |
AI tools can't ingest docs cleanly |
Misses Archon's core audience |
Hand-author llms.txt |
Full curation control |
Manual maintenance; drifts from docs |
Plugin auto-regenerates on every build |
| Custom Astro integration |
No third-party dep |
Reinvents a solved problem |
starlight-llms-txt is purpose-built and maintained |
Rely on existing sitemap.xml |
Already generated |
Not the llms.txt convention; tools look for /llms.txt specifically |
Doesn't solve discovery |
Scope
- Package(s) likely affected:
docs-web
- Breaking change? No — purely additive; existing routes unchanged
- Database changes needed? No
- New external dependencies? Yes —
starlight-llms-txt (dev dep on @archon/docs-web only, not shipped to users)
Security Considerations
- New permissions/capabilities? No
- New external network calls? No — build-time only; serves static files
- Secrets/tokens handling? No — re-serializes already-public markdown content
- No new trust boundary: same content as the HTML docs, just a different serialization
Definition of Done
Problem
https://archon.diy/llms.txtand/llms-full.txtboth return 404; the Starlight site atpackages/docs-web/has no llms.txt plugin configured.Proposed Solution
Add
starlight-llms-txtas a dev dependency of@archon/docs-web. The plugin reads existing markdown undersrc/content/docs/and generates three endpoints at build time:/llms.txt— index of all doc pages with titles and descriptions (llmstxt.org spec)/llms-full.txt— full markdown concatenation of all docs/llms-small.txt— trimmed variantImplementation touches two places:
packages/docs-web/package.json— addstarlight-llms-txttodevDependenciespackages/docs-web/astro.config.mjs— import the plugin and add it to theplugins:array in thestarlight()configUser Flow
Before (current)
After (proposed)
Alternatives Considered
llms.txtstarlight-llms-txtis purpose-built and maintainedsitemap.xmlllms.txtconvention; tools look for/llms.txtspecificallyScope
docs-webstarlight-llms-txt(dev dep on@archon/docs-webonly, not shipped to users)Security Considerations
Definition of Done
starlight-llms-txtadded topackages/docs-web/package.jsondevDependenciespackages/docs-web/astro.config.mjshttps://archon.diy/llms.txtreturns a valid index after deployhttps://archon.diy/llms-full.txtreturns full concatenated docsreference/index.mdor the site footer) pointing AI users at the URL