docs: add llms.txt for agent-readable repo orientation

[zuto-dev]

What

Adds a curated llms.txt at the repo root following the llmstxt.org spec, plus a tiny CI workflow that fails the build if any linked path stops resolving.

Why

Agents (Claude Code, Codex, Cursor, OpenCode, etc.) increasingly orient inside a codebase by reading llms.txt first. Without one, they re-scrape README.md and miss the website/docs/ tree where the real architecture and developer-guide content lives. With one, they land on the right routing index in their first read.

The pitch deliberately surfaces the two architectural invariants from AGENTS.md — per-conversation prompt caching is sacred and the core is a narrow waist; capability lives at the edges — so any agent reading the file lands on the contribution rubric the right way around (and is less likely to propose a new core tool when a skill or plugin would do).

Footprint

Per AGENTS.md's contribution rubric:

• "Expand reach at the edges" — agents are a real consumer of the repo. Adding agent-readable orientation is an edge expansion, not a core change.
• No new core tools, no new HERMES_* env vars, no plugin/core boundary changes. Pure documentation.
• Behavior contracts over snapshots — the CI check asserts an invariant (linked paths resolve), not a frozen list.
• CI runs unconditionally to avoid the path-gated "check pending forever" problem already documented in docs-site-checks.yml.

Verification

Locally:

broken=0
while IFS= read -r path; do
  [ -f "$path" ] || { echo "BROKEN: $path"; broken=$((broken+1)); }
done < <(grep -oE '\(([^)]+\.(md|mdx|example|yaml|yml))\)' llms.txt | tr -d '()')
echo "broken=$broken"
# broken=0

The CI workflow runs the same check on every PR.

Notes

• Curated, not auto-generated. The point of an index is curation; an auto-generated dump would defeat the purpose.
• v1 ships root-level only. A sub-area llms.txt per package (e.g. agent/llms.txt) is deferred until an external consumer asks.
• Spec reference: https://llmstxt.org/

[tonydwb]

Code Review Summary

Verdict: Approved

Adds llms.txt for agent-readable repository orientation. Documentation-only addition (104 lines). No code concerns.

---

Reviewed by Hermes Agent

[zuto-dev]

@teknium1 friendly bump on this one — docs-only addition (104 lines, llms.txt for agent-readable repo orientation). The Hermes-Agent auto-review approved (authorAssociation NONE so it doesn't satisfy branch protection). Could one of you give it a real review when you have a sec? Happy to rebase if anything has drifted.

[zuto-dev]

Closing — going to maintain this as a local convention for now. Thanks for taking a look, feel free to revive if useful later.