#134 docs: add llms.txt and llms-full.txt for AI-discoverable project context

[Anonymous]

Originally created by: kumaakh

Background

Suggested in PR [#133]. Fleet supports Claude, Gemini, Codex, and Copilot — the project context layer should be equally discoverable by all of them, not just Claude Code.

The llms.txt convention

The llms.txt spec (llmstxt.org) defines a standard markdown file at the repo root that AI agents use to understand a project. Format:

```markdown

Project name

Brief summary blockquote

Body paragraphs explaining the project.

Section (e.g. Docs)

• Doc name: one-line description

Optional

• Less critical doc: can be skipped for shorter context
  ```

llms-full.txt format

The full variant uses an XML-wrapped structure (same pattern as FastHTML's `llms-ctx-full.txt`, the reference implementation). Each document is wrapped in `<doc>` tags so the LLM knows where one ends and another begins:</doc>

```xml
<project title="Apra Fleet" summary="MCP server for orchestrating multiple agentic AI instances..."></project>

<docs>
<doc title="User Guide" desc="Installation, member registration, multi-provider setup">
[content of docs/user-guide.md]
</doc></docs>

<doc title="Vocabulary" desc="Fleet-specific terminology reference">
[content of docs/vocabulary.md]
</doc>

<doc title="Provider Matrix" desc="LLM provider capability comparison">
[content of docs/provider-matrix.md]
</doc>

<doc title="FAQ" desc="Common questions and answers">
[content of docs/FAQ.md]
</doc>

<doc title="Architecture" desc="Internal architecture and how fleet works">
[content of docs/architecture.md]
</doc>

```

Proposed approach

Single source of truth: humans maintain `CLAUDE.md` and `llms.txt`.

• `llms.txt` — humans maintain this file directly at the repo root, following the spec format (H1, blockquote, H2 sections with doc links). It is the index.
• `llms-full.txt` — CI generates this on every release by fetching the content of each doc listed in `llms.txt` and wrapping it in the XML structure above. Never hand-edited.

Note on CLAUDE.md

`CLAUDE.md` is the Claude Code agent context file — it contains agent-specific instructions and is separate from `llms.txt`. They serve different purposes and should remain independent files.

Acceptance criteria

• [ ] `llms.txt` added to repo root, maintained by humans, follows spec format
• [ ] CI `release` job generates `llms-full.txt` using the XML-wrapped structure
• [ ] `llms-full.txt` committed to repo root after each release (so it's readable without a build step)
• [ ] Docs listed in `llms.txt`: user-guide, vocabulary, provider-matrix, FAQ, architecture

[Anonymous]

Originally posted by: kumaakh

Fixed in commit 211f043 (PR [#128]). llms.txt added to repo root and maintained as the human-edited index. llms-full.txt is generated by CI on every build via scripts/gen-llms-full.mjs and committed to root — readable without a build step.

[Anonymous]

Ticket changed by: kumaakh

• status: open --> closed