diff --git a/README.md b/README.md
index 08e5add..6fa2a58 100644
--- a/README.md
+++ b/README.md
@@ -24,7 +24,8 @@ Docs: [shellicons.shellui.dev](https://shellicons.shellui.dev)
- [x] MAUI: typed controls, `IconName` dispatcher, `IconCatalog` metadata with alias lookup
- [x] Avalonia: typed controls, `Kind` dispatcher, inherited `Foreground`, the same `IconCatalog`
- [x] 168 tests (xUnit + bUnit + headless MAUI + headless Avalonia with Skia rendering), CI for both solutions, tag-driven release — see [RELEASING.md](RELEASING.md)
-- [x] Docs site at [docs/ShellIcons.Docs](docs/ShellIcons.Docs) (ShellDocs 0.1.11-alpha), with a searchable icon browser
+- [x] Docs site at [docs/ShellIcons.Docs](docs/ShellIcons.Docs) (ShellDocs 0.1.17-alpha), with a searchable icon browser
+- [x] Docs for AI agents: [`/llms.txt`](https://shellicons.shellui.dev/llms.txt), every page as Markdown, and `AGENTS.md` / `CLAUDE.md` / Copilot / Cursor rule files — see [AI Agents](https://shellicons.shellui.dev/docs/ai-agents)
- [x] Static build for GitHub Pages ([shellicons.shellui.dev](https://shellicons.shellui.dev)) — deploys on push to `main`
- [ ] MAUI: check rendering on Android/iOS devices, then publish
- [ ] Avalonia: run in a real desktop app, then publish
@@ -225,7 +226,7 @@ Serves at http://localhost:5145. Pages live in `docs/ShellIcons.Docs/content/doc
`/docs/icons` is a searchable browser of the entire catalog with click-to-copy component names.
-Build the static site the way the deploy workflow does (needs `dotnet tool install -g ShellDocs.CLI --version 0.1.11-alpha`):
+Build the static site the way the deploy workflow does (needs `dotnet tool install -g ShellDocs.CLI --version 0.1.17-alpha`):
```bash
cd docs/ShellIcons.Docs
diff --git a/docs/ShellIcons.Docs/Components/Pages/DocsPage.razor b/docs/ShellIcons.Docs/Components/Pages/DocsPage.razor
index 4003d59..f894646 100644
--- a/docs/ShellIcons.Docs/Components/Pages/DocsPage.razor
+++ b/docs/ShellIcons.Docs/Components/Pages/DocsPage.razor
@@ -16,11 +16,7 @@
}
else
{
-
+ ` markup, add another icon package, or copy icons from lucide.dev.
+2. **Names come from Lucide.** Every icon is PascalCase of its Lucide id: `chevron-right` is `ChevronRight`, `triangle-alert` is `TriangleAlert`. The catalog is pinned to the Lucide version on the Browse icons page, so an icon that is newer on lucide.dev may not exist yet; check the catalog before using a name. Renamed icons keep their new name only (`home` is `House`).
+3. **Blazor: import `ShellIcons` only.** One `@using ShellIcons` in `_Imports.razor` gives:
+ - `` with an `aria-label`. `@onclick` directly on an icon component throws; `onclick="@(() => Save())"` works if it must go on the icon.
+6. **Accessibility.** Icons are hidden from screen readers unless `Title` is set. Set `Title` when the icon is the only thing conveying meaning, such as an icon-only button without an `aria-label`.
+7. **MAUI.** `xmlns:icons="https://shellicons.dev/maui"`, then `
-
@@ -23,6 +23,8 @@
diff --git a/docs/ShellIcons.Docs/content/docs/ai-agents.md b/docs/ShellIcons.Docs/content/docs/ai-agents.md
new file mode 100644
index 0000000..4c75c81
--- /dev/null
+++ b/docs/ShellIcons.Docs/content/docs/ai-agents.md
@@ -0,0 +1,88 @@
+---
+title: AI Agents
+description: Point Claude Code, Cursor, Copilot and other coding agents at the ShellIcons docs, so they use its icons instead of pasting SVG.
+---
+
+# AI Agents
+
+ShellIcons publishes these docs for AI coding agents in the [llms.txt](https://llmstxt.org) format. An agent that reads them knows how to install ShellIcons, which import to use, how icons are named and how each target (Blazor, MAUI, Avalonia) works, so it doesn't paste raw SVG or pull in another icon package.
+
+## Set up your project
+
+Coding agents read an instructions file in the project root at the start of every session. Add ShellIcons' rules to the one your agent reads: they tell it to use ShellIcons' components, which names and imports to use, and where these docs are. Each file is a `## ShellIcons` section, so the commands append it to a file you already have, or create the file.
+
+
+
+
+Claude Code reads `CLAUDE.md`. [Download CLAUDE.md](/agents/CLAUDE.md), or run this in the project root:
+
+```bash
+curl -fsSL https://shellicons.shellui.dev/agents/CLAUDE.md >> CLAUDE.md
+```
+
+
+
+
+Cursor reads rules from `.cursor/rules`. [Download shellicons.mdc](/agents/shellicons.mdc) into that folder, or run this in the project root:
+
+```bash
+curl -fsSL --create-dirs -o .cursor/rules/shellicons.mdc https://shellicons.shellui.dev/agents/shellicons.mdc
+```
+
+
+
+
+Copilot reads `.github/copilot-instructions.md`. [Download copilot-instructions.md](/agents/copilot-instructions.md) into `.github`, or run this in the project root:
+
+```bash
+mkdir -p .github && curl -fsSL https://shellicons.shellui.dev/agents/copilot-instructions.md >> .github/copilot-instructions.md
+```
+
+
+
+
+Codex and many other agents read `AGENTS.md`. [Download AGENTS.md](/agents/AGENTS.md), or run this in the project root:
+
+```bash
+curl -fsSL https://shellicons.shellui.dev/agents/AGENTS.md >> AGENTS.md
+```
+
+
+
+
+When you upgrade ShellIcons, replace the file's `## ShellIcons` section with a fresh copy.
+
+## Or ask the agent
+
+Paste this into your agent to have it read the docs and set up the instructions file itself:
+
+```text
+Read https://shellicons.shellui.dev/llms.txt and follow its rules in this project.
+Then add the ShellIcons section from https://shellicons.shellui.dev/agents/AGENTS.md
+to the instructions file you read at startup (AGENTS.md, CLAUDE.md or
+.github/copilot-instructions.md), creating it if it doesn't exist.
+```
+
+For a one-off task, give it the docs with the task:
+
+```text
+Read https://shellicons.shellui.dev/llms.txt, then add icons to the sidebar links.
+```
+
+## What agents can read
+
+| URL | Contents |
+|-----|----------|
+| [`/llms.txt`](/llms.txt) | Rules for agents, then every page of these docs with a one-line description and, where a page has one, its install command |
+| [`/llms-full.txt`](/llms-full.txt) | The rules and every page as Markdown in one file, examples included |
+| Any page + `.md` | One page as Markdown, for example [`/docs/guides/sizing-and-stroke.md`](/docs/guides/sizing-and-stroke.md) |
+
+Every page also has a ⋯ menu next to its title: **Copy page** copies its Markdown, **View as Markdown** opens it, and **Open in Claude** and **Open in ChatGPT** start a chat that reads it.
+
+## What the rules say
+
+- Render icons with ShellIcons instead of pasting `` markup or adding another icon package.
+- Icon names are PascalCase Lucide ids (`chevron-right` → `ChevronRight`); check the catalog, since lucide.dev may be ahead of the pinned version.
+- In Blazor, import `ShellIcons` only and use ``, and set `Title` when the icon carries meaning on its own.
+- On MAUI use `