feat(docs): publish validated agent discovery

.github/workflows/book.yml

@@ -22,13 +22,21 @@ jobs:
       - name: Check documented dependency versions
         run: bun scripts/check-versions.ts
 
+      - name: Check documentation structure and links
+        run: bun scripts/check-docs.ts
+
       - name: Build Vocs
         run: cd vocs && bun install --frozen-lockfile && bun run build
 
       - name: Check generated discovery files
         run: |
           test -f vocs/dist/public/sitemap.xml
           test -f vocs/dist/public/robots.txt
+          test -f vocs/dist/public/llms.txt
+          test -f vocs/dist/public/llms-full.txt
+          test -f vocs/dist/public/agent-index.json
+          if grep -q '](/' vocs/dist/public/llms.txt; then exit 1; fi
+          if grep -q '](/' vocs/dist/public/llms-full.txt; then exit 1; fi
           test ! -d vocs/dist/public/templates
 
       # Only prepare for deploy if a push to main

AGENTS.md

@@ -0,0 +1,43 @@
+# Alloy documentation agent guide
+
+## Scope and source of truth
+
+- Hand-written pages live in `vocs/docs/pages`; primary navigation lives in `vocs/sidebar.ts`.
+- `vocs/versions.ts` is the single version source for hand-written dependency snippets.
+- Generated example pages and snippets come from `alloy-rs/examples`. Do not edit files carrying a
+  `DO NOT EDIT` header; update the source example or template and run `scripts/update.sh`.
+- Verify exact Alloy symbols and feature gates against the matching release on docs.rs or the
+  `alloy-rs/alloy` source. The website is explanatory documentation, not the API definition.
+
+## Content rules
+
+- Use task-oriented titles and frontmatter descriptions containing the terms a reader will search.
+- State required Cargo features, environment variables, node capabilities, and external binaries.
+- Use `RPC_URL`, `WS_URL`, and `IPC_PATH` instead of shared endpoints or credentials.
+- Link concepts to a runnable example and exact API documentation where possible.
+- Distinguish primitives, consensus types, RPC types, and network-associated types.
+- Keep internal links root-relative; use absolute URLs for other repositories and sites.
+
+## Validation
+
+Run from the repository root:
+
+```sh
+bun scripts/check-versions.ts
+bun scripts/check-docs.ts
+actionlint
+shellcheck scripts/update.sh
+cd vocs && bun install --frozen-lockfile && bun run build
+```
+
+The build post-processes `llms.txt`, `llms-full.txt`, and `agent-index.json`. Confirm all three exist
+under `vocs/dist/public`. Compile new Rust snippets against the documented Alloy release; rendering
+Markdown is not proof that a snippet compiles.
+
+## Agent retrieval artifacts
+
+- `https://alloy.rs/agent-index.json`: versioned page inventory and task-to-page map.
+- `https://alloy.rs/llms.txt`: compact page inventory.
+- `https://alloy.rs/llms-full.txt`: complete corpus; use only when page retrieval is unavailable.
+- `https://github.com/alloy-rs/examples/blob/main/examples-index.json`: runnable example metadata once
+  the corresponding examples catalog change is available on the default branch.

CONTRIBUTING.md

@@ -122,6 +122,10 @@ To perform an update of generated output inspect and run `./scripts/update.sh`.
 To add a new page, create it under `./vocs/docs/pages` and add it to
 `./vocs/sidebar.ts` when it should appear in the primary navigation.
 
+Every hand-written page must have a frontmatter description. Use root-relative internal links and
+run `bun scripts/check-docs.ts` from the repository root before building. The build generates the
+agent inventories, so new task areas should also be represented in `scripts/build-agent-index.ts`.
+
 ### Discuss and update
 
 You will probably get feedback or requests for changes to your Pull Request.

README.md

@@ -4,6 +4,10 @@ Documentation for all things Alloy.
 
 View the docs [here](https://alloy.rs/).
 
+Machine-readable discovery is available through
+[`agent-index.json`](https://alloy.rs/agent-index.json), [`llms.txt`](https://alloy.rs/llms.txt), and
+[`llms-full.txt`](https://alloy.rs/llms-full.txt).
+
 ## Contributing
 
 Thanks for your help improving the project! We are so happy to have you! We have