Publish machine-readable docs for AI coding agents embedding the kernel (llms.txt bundle)

[dgenio]

Summary

Provide an llms.txt (and a concatenated llms-full.txt-style bundle) curating the
kernel's public API, invariants, and integration recipes for downstream AI coding
assistants — the tooling-facing complement to the repo's excellent contributor-facing
agent docs.

Why this matters

This project's adopters are disproportionately people building agents with AI
coding assistants. The repo already invests heavily in agent-readable docs for its
own contributors (AGENTS.md, docs/agent-context/), but a coding assistant helping
a user integrate weaver-kernel into their app sees none of that unless it crawls
the repo. A curated, single-fetch context file (the emerging llms.txt convention)
makes "have Claude/Copilot wire weaver-kernel into my agent" dramatically more
reliable — a low-cost, high-fit adoption lever for precisely this audience.

Current evidence

• AGENTS.md, .claude/CLAUDE.md, .github/copilot-instructions.md, and docs/agent-context/ exist — all oriented to contributors modifying this repo, not users embedding it.
• No llms.txt at the repo root; no single-file API+recipes bundle exists.
• docs/tutorial.md, docs/capabilities.md, and 9 runnable examples provide the raw material to curate.

External context

The llms.txt convention (https://llmstxt.org/) is increasingly adopted by
developer-tool projects to expose curated, LLM-sized documentation entry points.

Proposed implementation

1. Author llms.txt: one-paragraph project description, links ordered by
   integration importance (quickstart, capabilities, security model, API reference).
2. Add a small build script (stdlib only) that concatenates curated docs + public
   API signatures into a bundled context file; wire into CI so it cannot go stale
   (regenerate and diff-check).
3. Include the integration-recipe examples verbatim (they are CI-tested via
   make example, so the bundle inherits correctness).
4. Mention the file in README so humans can hand it to their assistant.

AI-agent execution notes

• Inspect first: README.md, docs/tutorial.md, docs/capabilities.md, examples/readme_quickstart.py, __init__.py public exports.
• Keep curation small (the value is selection, not volume).
• Edge cases: doc drift — the CI diff-check is the guard; do not hand-duplicate content that can be concatenated.
• This is docs/tooling only: no library code changes.

Acceptance criteria

• llms.txt exists at the repo root following the convention's structure.
• The bundle regenerates deterministically in CI and fails on drift.
• README references the file.

Test plan

CI regeneration check; manual smoke: feed the bundle to an assistant and ask it to
produce the quickstart (spot validation). Run make ci.

Documentation plan

The deliverable is documentation; CHANGELOG Added.

Migration and compatibility notes

Not expected to require migration.

Risks and tradeoffs

Another artifact to maintain — automation and CI checks keep cost near zero.
Convention is young; the file is useful even as plain curated docs if the
convention shifts.

Suggested labels

ai, documentation, adoption, developer-experience