Shewart · Oct 20, 2026 · Oct 19, 2026 · Oct 19, 2026
diff --git 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
@@ -16,11 +16,7 @@
 }
 else
 {
-    <div class="doc-not-found">
-        <h1>Page not found</h1>
-        <p>The page <code>@Path</code> doesn't exist yet.</p>
-        <p><a href="/docs/introduction"><svg viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align:middle;margin-right:0.35rem"><path d="M19 12H5M12 19l-7-7 7-7"/></svg>Back to introduction</a></p>
-    </div>
+    <DocsNotFound />
 }
 
 @code {

diff --git a/docs/ShellIcons.Docs/Llms/agent-rules.md b/docs/ShellIcons.Docs/Llms/agent-rules.md
@@ -0,0 +1,18 @@
+## Rules for AI agents
+
+Read these before adding icons to a project that uses ShellIcons.
+
+1. **Use ShellIcons; don't paste SVG.** If the project references `ShellIcons.Blazor`, `ShellIcons.Maui` or `ShellIcons.Avalonia`, render icons with it. Don't paste inline `<svg>` 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:
+   - `<ChevronRightIcon />` suffixed components for markup (the default);
+   - `@Icon.ChevronRight()` for icons as values, such as `RenderFragment` parameters and lists built in C#;
+   - `<ShellIcon Name="chevron-right" />` only for names known at runtime (it keeps every icon in the build).
+   Never add `@using ShellIcons.Icons` to `_Imports.razor`: its short names (`Badge`, `Table`, `Menu`, `Router`, …) collide with UI-kit components (RZ9985). Razor ignores `@using` aliases for tags, so `<Icon.Plus />` renders nothing.
+4. **Blazor: color and size like text.** Icons draw with `currentColor`, so set the color on the icon or its parent (`Class="text-destructive"`). `Size` is a string (`Size="16"`, `Size="1.25em"`); `StrokeWidth` defaults to 2; `AbsoluteStroke="true"` keeps the stroke width constant at any size.
+5. **Blazor: put click handlers on a button.** Wrap the icon in a `<button>` 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 `<icons:ChevronRight Size="16" />` or `<icons:Icon Name="Search" Color="{DynamicResource Primary}" />`. Icons don't take the text color; set `Color`, or style `icons:IconView` once.
+8. **Avalonia.** `xmlns:icons="https://shellicons.dev/avalonia"`, then `<icons:ChevronRight Size="16" />` or `<icons:Icon Kind="Search" />` (the dispatcher property is `Kind`, because `Name` is taken). `Foreground` is inherited, so icons match the surrounding text.
+9. **Names from strings in XAML apps.** `IconCatalog.TryParse("home", out var name)` accepts ids, PascalCase names and Lucide aliases; `IconCatalog.Search("cart")` powers pickers.
+10. **Custom icons** go in the ShellIcons repo's `catalog/custom/icons/` as 24×24 stroke SVGs; they aren't added from application code.
diff --git a/docs/ShellIcons.Docs/Program.cs b/docs/ShellIcons.Docs/Program.cs
@@ -14,11 +14,21 @@
     o.SiteName = "ShellIcons";
     o.SiteTagline = "Lucide-derived icons for Blazor, .NET MAUI and Avalonia.";
     o.GitHubRepo = "shellui-dev/shell-icons";
+    o.SiteUrl = "https://shellicons.shellui.dev";
     o.LayoutVariant = DocsLayoutVariant.Sidebar;
     o.SetLogo("/images/logo-light.svg", "/images/logo-dark.svg", "ShellIcons");
 
+    // /llms.txt, every page as Markdown, agent instruction files and the page actions menu.
+    o.EnableLlmsTxt(l =>
+    {
+        l.Summary = "ShellIcons is the Lucide icon set for .NET: typed components for Blazor (inline SVG), and native controls for .NET MAUI and Avalonia, generated from one catalog at build time.";
+        l.RulesFile = "Llms/agent-rules.md";
+        l.InstallCommandPattern = @"dotnet add package ShellIcons\.\w+(?: --version \S+)?";
+    });
+
     o.AddNavLink("Docs", "/docs/introduction");
     o.AddNavLink("Icons", "/docs/icons");
+    o.AddNavLink("AI Agents", "/docs/ai-agents");
     o.AddNavLink("GitHub", "https://github.com/shellui-dev/shell-icons");
 
     // Every icon component, usable in razor:preview blocks.

diff --git a/docs/ShellIcons.Docs/ShellIcons.Docs.csproj b/docs/ShellIcons.Docs/ShellIcons.Docs.csproj
@@ -10,10 +10,10 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="ShellDocs.Tokens" Version="0.1.11-alpha" />
-    <PackageReference Include="ShellDocs.Components" Version="0.1.11-alpha" />
-    <PackageReference Include="ShellDocs.Core" Version="0.1.11-alpha" />
-    <PackageReference Include="ShellDocs.Markdown" Version="0.1.11-alpha" />
+    <PackageReference Include="ShellDocs.Tokens" Version="0.1.17-alpha" />
+    <PackageReference Include="ShellDocs.Components" Version="0.1.17-alpha" />
+    <PackageReference Include="ShellDocs.Core" Version="0.1.17-alpha" />
+    <PackageReference Include="ShellDocs.Markdown" Version="0.1.17-alpha" />
   </ItemGroup>
 
   <ItemGroup>
@@ -23,6 +23,8 @@
   <ItemGroup>
     <Content Include="content/**/*.md" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />
     <Content Update="content/**/meta.json" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />
+    <!-- Agent rules for /llms.txt and the downloadable agent instruction files -->
+    <None Update="Llms/*.md" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />
   </ItemGroup>
 
 </Project>
diff --git a/docs/ShellIcons.Docs/content/docs/ai-agents.md 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.
+
+<DocsTabs>
+<DocsTab Label="Claude Code">
+
+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
+```
+
+</DocsTab>
+<DocsTab Label="Cursor">
+
+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
+```
+
+</DocsTab>
+<DocsTab Label="GitHub Copilot">
+
+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
+```
+
+</DocsTab>
+<DocsTab Label="Other agents">
+
+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
+```
+
+</DocsTab>
+</DocsTabs>
+
+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 `<svg>` 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 `<ChevronRightIcon />`, `@Icon.ChevronRight()` or `<ShellIcon Name="…" />`; never import `ShellIcons.Icons` globally.
+- Color icons like text, put click handlers on a wrapping `<button>`, and set `Title` when the icon carries meaning on its own.
+- On MAUI use `<icons:Icon Name="…" Color="…" />`; on Avalonia `<icons:Icon Kind="…" />` with an inherited `Foreground`.
diff --git a/docs/ShellIcons.Docs/content/docs/icons.md b/docs/ShellIcons.Docs/content/docs/icons.md
@@ -6,6 +6,6 @@ order: 2
 
 # Browse icons
 
-Every icon in ShellIcons, from Lucide 0.475.0. The same names work in Blazor (`<ChevronRightIcon />`) and MAUI (`<icons:ChevronRight />`).
+Every icon in ShellIcons, from Lucide 0.475.0. The same names work in Blazor (`<ChevronRightIcon />`) and in MAUI and Avalonia XAML (`<icons:ChevronRight />`).
 
 <IconBrowser />
diff --git a/docs/ShellIcons.Docs/content/docs/meta.json b/docs/ShellIcons.Docs/content/docs/meta.json
@@ -3,6 +3,7 @@
   "pages": [
     "introduction",
     "icons",
+    "ai-agents",
     "getting-started",
     "guides",
     "maui",