docs: adds descriptions to links in llms-txt

[nicholasjameshall]

Description

This change makes the llms.txt files easier to navigate for agents.

Currently we have two layers of llms.txt file:

• Overview (root-level): https://ucp.dev/llms.txt
• Specifications: https://ucp.dev/[version]/llms.txt (e.g. https://ucp.dev/latest/llms.txt, https://ucp.dev/2026-04-08/llms.txt)

There are two main problems:

1. These docs are sparse. The agent would need to infer from one or two words how to find the correct document to read.
2. These live independently of one another (i.e. from the root-level llms.txt file, there's no direct link to the versioned specification llms.txt files, and vice-versa).

This change does the following:

• Adds an introduction to all llms.txt files. If the agent lands on the root-level llms.txt file, it will know how to get to the versioned specification files.
• Adds descriptions to all links to better help the agent navigate.

Note: I set the category as "infra" since, although this touches docs, it doesn't actually change any content.

Category (Required)

Please select one or more categories that apply to this change.

• Core Protocol: Changes to the base communication layer, global context, or breaking refactors. (Requires Technical Council approval)
• Governance/Contributing: Updates to GOVERNANCE.md, CONTRIBUTING.md, or CODEOWNERS. (Requires Governance Council approval)
• Capability: New schemas (Discovery, Cart, etc.) or extensions. (Requires Maintainer approval)
• Documentation: Updates to README, or documentations regarding schema or capabilities. (Requires Maintainer approval)
• Infrastructure: CI/CD, Linters, or build scripts. (Requires DevOps Maintainer approval)
• Maintenance: Version bumps, lockfile updates, or minor bug fixes. (Requires DevOps Maintainer approval)
• SDK: Language-specific SDK updates and releases. (Requires DevOps Maintainer approval)
• Samples / Conformance: Maintaining samples and the conformance suite. (Requires Maintainer approval)
• UCP Schema: Changes to the ucp-schema tool (resolver, linter, validator). (Requires Maintainer approval)
• Community Health (.github): Updates to templates, workflows, or org-level configs. (Requires DevOps Maintainer approval)

Related Issues

Checklist

• I have followed the Contributing Guide.
• I have updated the documentation (if applicable).
• My changes pass all local linting and formatting checks.
• (For Core/Capability) I have included/updated the relevant JSON schemas.
• I have regenerated Python Pydantic models by running generate_models.sh under python_sdk.

Screenshots / Logs (if applicable)

[damaz91]

do we also want to include "draft"?

[nicholasjameshall]

I considered it but I'm not sure when this would be actually useful to the llm?

[aksbro-gpu]

+1, not sure if draft would be useful. Should we just focus on formally released versions?

[damaz91]

it might be useful to 1) assess differences between the current version and the draft version 2) start working on the draft version before it releases. But I understand this might ultimately confuse the LLM so I'm also fine to exclude it.

[nicholasjameshall]

I wonder if this is a common use case (working on the new version before it's actually released) given how unstable it is. For the time being I'll omit it and we can revisit.

[aksbro-gpu]

Will this description be autoupdated as we launch new features? If not, then lets make the language future proof and not call out specific features

[nicholasjameshall]

It won't, but I think we should add something (GitHub action?) to ensure that this is kept up-to-date as documentation changes or the nav section in this yml is updated (just so that the llms.txt isn't left behind). For now I'll make it more future-proof as you called out and we can discuss this elsewhere.

[jingyli]

nit: Can we instead say commerce actions (i.e., discovering, buying) on behalf of users here instead given UCP is more than just transaction placement?