Shewart · Oct 19, 2026 · Oct 19, 2026 · Oct 19, 2026 · Oct 19, 2026 · Oct 19, 2026
diff --git a/.github/workflows/deploy-pages.yml b/.github/workflows/deploy-pages.yml
@@ -58,7 +58,7 @@ jobs:
       # use. Prevents a floating latest-prerelease install from silently
       # shifting the prerender behaviour under our feet mid-release-cycle.
       - name: Install shelldocs CLI
-        run: dotnet tool install -g ShellDocs.CLI --version 0.1.15-alpha
+        run: dotnet tool install -g ShellDocs.CLI --version 0.1.17-alpha
 
       # Restore explicitly so the `shelldocs build`'s embedded `dotnet
       # publish` doesn't spend the first run downloading every package

diff --git a/Components/App.razor b/Components/App.razor
@@ -12,11 +12,6 @@
     <link rel="stylesheet" href="_content/ShellDocs.Tokens/tokens.css" />
     <link rel="stylesheet" href="_content/ShellDocs.Components/shelldocs-theme.css" />
     <link rel="stylesheet" href="ShellDocs.Site.styles.css" />
-    @* ShellDocs 0.1.15 scopes this rule so it never matches, and an inline LogoSvg
-       with no width of its own renders 0px wide. Remove once that is fixed upstream. *@
-    <style>
-        .brand-logo-svg > svg { height: 100%; width: auto; display: block; }
-    </style>
     <script>
         (function () {
             var saved = null;

diff --git a/Components/Pages/Home.razor b/Components/Pages/Home.razor
@@ -46,9 +46,6 @@
 
 <SiteFooter />
 
-@* HomeLayout has no search dialog of its own; this one makes Ctrl+K and the bento's search panel work here. *@
-<SearchDialog />
-
 <style>
     .site-home {
         max-width: 68rem;

diff --git a/Llms/agent-rules.md b/Llms/agent-rules.md
@@ -0,0 +1,11 @@
+## Rules for AI agents
+
+Read these before building or changing a ShellDocs site.
+
+1. **Install with the CLI.** `dotnet tool install -g ShellDocs.CLI --prerelease`, then `shelldocs init` for a new site or in an existing Blazor Web App. Keep the `ShellDocs.*` package versions and the CLI version the same.
+2. **Pages are Markdown files** in `content/docs/`, with `title` and `description` frontmatter. Each folder's `meta.json` sets the sidebar order and must list every page. `shelldocs add page|guide|component <name>` scaffolds one. New pages and `meta.json` edits need a restart of the running site.
+3. **Use ShellDocs' components in Markdown; don't write HTML look-alikes.** `<Callout>`, `<Tabs>` / `<Tab>`, `<Steps>` / `<Step>`, `<CardGrid>` / `<Card>` / `<LinkCard>`, `<CodeGroup>`, `<FileTree>`, `<TypeTable>` / `<TypeRow>` and `<AutoTypeTable>`. When a site's own library has a component of the same name, the `Docs` prefix (`<DocsCallout>`) still reaches the built-in.
+4. **Live examples:** a ```` ```razor:preview ```` fence, `<ComponentPreview>`, or `<DemoPreview Component="X" />` for a `.razor` file under `DemoSourceRoot`. A `razor:preview` body is Razor, not Markdown: use `<code>` and `<strong>`, not backticks and `**`. Components used in Markdown must be registered with `RegisterComponent<T>()` or `RegisterComponentsFromAssembly<T>()`.
+5. **Attribute values on tags in Markdown are plain text.** They aren't Markdown and HTML entities aren't decoded. There is no escape for the quote character, so switch between single and double quotes.
+6. **Configuration lives in `AddShellDocs(o => ...)` in `Program.cs`:** site details, navigation, packages, versions, redirects, previews and `EnableLlmsTxt`.
+7. **Static sites come from `shelldocs build`.** Don't edit the `publish/` output by hand, and don't add `--spa-fallback` unless the host needs it: it replaces the not-found page with the home page.
diff --git a/Program.cs b/Program.cs
@@ -23,6 +23,15 @@
     o.RegisterComponentsFromAssembly<App>("ShellDocs.Site.Components.Demos");
     o.DemoSourceRoot = Path.Combine(builder.Environment.ContentRootPath, "Components", "Demos");
 
+    // /llms.txt, every page as Markdown at its URL + ".md", agent instruction
+    // files and the page actions menu by the title.
+    o.EnableLlmsTxt(l =>
+    {
+        l.Summary = "ShellDocs is a docs framework for .NET: Markdown pages, live Blazor component previews, search and a static export, in a Blazor Web App.";
+        l.RulesFile = "Llms/agent-rules.md";
+        l.InstallCommandPattern = @"(?m)(?<=^[ \t]*)dotnet (?:tool install -g ShellDocs\.CLI|add package ShellDocs\.\w+)[^\r\n]*";
+    });
+
     // Top nav: three tabs. Package-specific navigation lives entirely in the
     // sidebar's package selector, not up here.
     o.AddNavLink("Documentation", "/docs/introduction");

diff --git a/README.md b/README.md
@@ -58,7 +58,7 @@ content/
       configuration.md
     authoring/          frontmatter, code fences, razor:preview, inline tags, navigation
     components/         one page per content primitive
-    guides/             component libraries, versioning, redirects, search, not-found, deployment
+    guides/             component libraries, versioning, redirects, search, llms.txt, not-found, deployment
     cli/                init, add, dev, build
     theming.md
     packages/           one overview per NuGet package
@@ -68,6 +68,8 @@ wwwroot/
   demos/                static pages shown with <IframePreview>
   cli-replay.js         the terminal replay on the home page
   copy-button.js        copy buttons marked with data-copy
+Llms/
+  agent-rules.md        rules for AI agents, shown in /llms.txt and the agent files
 Components/
   Demos/                demo components shown with <DemoPreview>
   Home/                 the animated feature bento on the home page
@@ -76,7 +78,7 @@ Components/
 
 ## Framework version
 
-The site references `ShellDocs.* 0.1.15-alpha`. On a new release, bump the four package versions in `ShellDocs.Site.csproj` and the CLI version pinned in `.github/workflows/deploy-pages.yml` together.
+The site references `ShellDocs.* 0.1.17-alpha`. On a new release, bump the four package versions in `ShellDocs.Site.csproj` and the CLI version pinned in `.github/workflows/deploy-pages.yml` together.
 
 ## License
 

diff --git a/ShellDocs.Site.csproj b/ShellDocs.Site.csproj
@@ -19,10 +19,10 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="ShellDocs.Components" Version="0.1.15-alpha" />
-    <PackageReference Include="ShellDocs.Core"       Version="0.1.15-alpha" />
-    <PackageReference Include="ShellDocs.Markdown"   Version="0.1.15-alpha" />
-    <PackageReference Include="ShellDocs.Tokens"     Version="0.1.15-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" />
+    <PackageReference Include="ShellDocs.Tokens"     Version="0.1.17-alpha" />
   </ItemGroup>
 
   <ItemGroup>
@@ -32,6 +32,8 @@
     <Content Update="content/**/meta.json" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />
     <!-- DemoPreview reads these at runtime; the Razor SDK drops .razor files from publish otherwise. -->
     <None Include="Components/Demos/**/*.razor" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />
+    <!-- EnableLlmsTxt reads the rules file at runtime, from the output folder and from the export's publish. -->
+    <None Update="Llms/agent-rules.md" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />
   </ItemGroup>
 
 </Project>
diff --git a/content/docs/authoring/fenced-code.md b/content/docs/authoring/fenced-code.md
@@ -1,6 +1,6 @@
 ---
 title: Fenced code
-description: Regular code fences : language detection, copy button, Shiki syntax highlighting.
+description: "Regular code fences: language detection, copy button, Shiki syntax highlighting."
 order: 2
 ---
 
@@ -109,7 +109,7 @@ dotnet add package ShellDocs.Components --prerelease
 <CodeTab Label="PackageReference">
 
 ```xml
-<PackageReference Include="ShellDocs.Components" Version="0.1.15-alpha" />
+<PackageReference Include="ShellDocs.Components" Version="0.1.17-alpha" />
 ```
 
 </CodeTab>

diff --git a/content/docs/authoring/razor-preview.md b/content/docs/authoring/razor-preview.md
@@ -24,7 +24,13 @@ This renders as a real Callout component.
 </Callout>
 ```
 
-The tags must be components registered with ShellDocs : the built-in primitives, or [your own](/docs/guides/component-libraries).
+The tags can be components registered with ShellDocs : the built-in primitives, or [your own](/docs/guides/component-libraries). A fence of plain HTML renders live too:
+
+```razor:preview
+<p style="margin:0">A fence with <strong>only HTML</strong> and no component.</p>
+```
+
+A fence with no tags at all stays a code block, and a warning is logged. Before `0.1.17-alpha` an HTML-only fence also rendered as a code block.
 
 ## The body is Razor, not markdown
 

diff --git a/content/docs/cli/build.md b/content/docs/cli/build.md
@@ -48,6 +48,9 @@ Requests a URL that doesn't exist and saves the site's not-found view as `404.ht
 <Step Title="Copies the search index">
 Saves the app's search index as `_shelldocs/search.json`, which is what makes search work without a server.
 </Step>
+<Step Title="Writes the llms.txt files">
+On a site that calls `EnableLlmsTxt`, writes `llms.txt`, `llms-full.txt`, every page's `.md` and the agent files. Their links use `--site-url`, then `SiteUrl`. See [AI agents (llms.txt)](/docs/guides/llms-txt).
+</Step>
 <Step Title="Copies the assets">
 Merges the published `wwwroot` into the output: framework scripts, `shelldocs.js`, stylesheets, your own static files. Prerendered pages are never overwritten.
 </Step>

diff --git a/content/docs/cli/init.md b/content/docs/cli/init.md
@@ -44,7 +44,7 @@ The single-page router that serves every `/docs/**` URL from the `.md` files und
 Deletes `Counter.razor`, `Weather.razor`, `NavMenu.razor`, `MainLayout.razor.css`, `Home.razor.css`. Rewrites `MainLayout.razor` as a bare pass-through and replaces `Home.razor` with the ShellDocs welcome page.
 </Step>
 <Step Title="Patches `Program.cs`">
-Adds `using ShellDocs.Components;`, `builder.WebHost.UseStaticWebAssets();`, and `builder.Services.AddShellDocs(...)` : anchoring on the exact template shape produced by `dotnet new blazor`.
+Adds `using ShellDocs.Components;`, `builder.WebHost.UseStaticWebAssets();`, and `builder.Services.AddShellDocs(...)` : anchoring on the exact template shape produced by `dotnet new blazor`. The `AddShellDocs` call turns on [llms.txt for AI agents](/docs/guides/llms-txt) with `o.EnableLlmsTxt(...)`, its options commented out.
 </Step>
 <Step Title="Patches `Components/App.razor`">
 Adds the `_content/ShellDocs.Tokens/tokens.css` and component CSS links, the theme-bootstrap script, and `shelldocs.js` + Shiki loader. Also switches `<Routes />` to `<Routes @rendermode="InteractiveServer" />` so interactive components (theme toggle, search, tabs) come alive.

diff --git a/content/docs/components/card.md b/content/docs/components/card.md
@@ -1,6 +1,6 @@
 ---
 title: Card
-description: A titled, described tile : linkable, groupable, iconable. The building block behind CardGrid.
+description: "A titled, described tile: linkable, groupable, iconable. The building block behind CardGrid."
 order: 2
 ---
 

diff --git a/content/docs/components/code-group.md b/content/docs/components/code-group.md
@@ -21,7 +21,7 @@ dotnet add package ShellDocs.Components --prerelease
 <CodeTab Label="PackageReference">
 
 ```xml
-<PackageReference Include="ShellDocs.Components" Version="0.1.15-alpha" />
+<PackageReference Include="ShellDocs.Components" Version="0.1.17-alpha" />
 ```
 
 </CodeTab>
@@ -41,7 +41,7 @@ dotnet add package ShellDocs.Components --prerelease
 <CodeTab Label="PackageReference">
 
 ```xml
-<PackageReference Include="ShellDocs.Components" Version="0.1.15-alpha" />
+<PackageReference Include="ShellDocs.Components" Version="0.1.17-alpha" />
 ```
 
 </CodeTab>
@@ -63,7 +63,7 @@ dotnet add package ShellDocs.Core --prerelease
 <CodeTab Label="PackageReference">
 
 ```xml
-<PackageReference Include="ShellDocs.Core" Version="0.1.15-alpha" />
+<PackageReference Include="ShellDocs.Core" Version="0.1.17-alpha" />
 ```
 
 </CodeTab>
@@ -80,7 +80,7 @@ dotnet add package ShellDocs.Markdown --prerelease
 <CodeTab Label="PackageReference">
 
 ```xml
-<PackageReference Include="ShellDocs.Markdown" Version="0.1.15-alpha" />
+<PackageReference Include="ShellDocs.Markdown" Version="0.1.17-alpha" />
 ```
 
 </CodeTab>

diff --git a/content/docs/getting-started/configuration.md b/content/docs/getting-started/configuration.md
@@ -27,7 +27,7 @@ That is a working site. The built-in content primitives are registered for you.
 <TypeRow Name="SiteName" Type="string" Default="empty" Required="true" Description="Brand name shown in the header and sidebar." />
 <TypeRow Name="SiteTagline" Type="string?" Default="—" Description="One-line description shown in the footer." />
 <TypeRow Name="GitHubRepo" Type="string?" Default="—" Description="Owner and repository, for example my-org/my-docs. Used for the GitHub link and as the default issue tracker." />
-<TypeRow Name="SiteUrl" Type="string?" Default="—" Description="Absolute address of the deployed site. Used in the links the preview menu builds." />
+<TypeRow Name="SiteUrl" Type="string?" Default="—" Description="Absolute address of the deployed site. Used in the links the preview menu builds and in the llms.txt files." />
 <TypeRow Name="IssueTrackerUrl" Type="string?" Default="GitHubRepo issues" Description="Where the preview menu's Report a bug and Suggest something open a new issue. With neither this nor GitHubRepo set, those items are hidden." />
 <TypeRow Name="ContentRoot" Type="string" Default="content" Description="Path to the content folder." />
 </TypeTable>
@@ -157,6 +157,23 @@ o.AddSyncSwitch("platform", "MAUI", "Avalonia");
 
 Both are covered in [Code tabs on previews](/docs/components/code-tabs).
 
+## AI agents
+
+<TypeTable>
+<TypeRow Name="EnableLlmsTxt(configure)" Type="method" Description="Serves /llms.txt, /llms-full.txt, every page as Markdown and agent instruction files, and adds the page actions menu by the title." />
+<TypeRow Name="LlmsTxt" Type="LlmsTxtOptions?" Default="null" Description="The options EnableLlmsTxt set. Null while it is off." />
+</TypeTable>
+
+```csharp
+o.EnableLlmsTxt(l =>
+{
+    l.RulesFile = "Llms/agent-rules.md";
+    l.InstallCommandPattern = @"dotnet add package MyLib\.\w+";
+});
+```
+
+The options and the files are covered in [AI agents (llms.txt)](/docs/guides/llms-txt).
+
 ## Options that do nothing yet
 
 `Theme` and the `--theme` flag of `shelldocs init` are accepted but have no effect in this release. Every site uses the same tokens; restyle through [Theming](/docs/theming).
@@ -177,6 +194,13 @@ builder.Services.AddShellDocs(o =>
     o.RegisterComponentsFromAssembly<App>("ShellDocs.Site.Components.Demos");
     o.DemoSourceRoot = Path.Combine(builder.Environment.ContentRootPath, "Components", "Demos");
 
+    o.EnableLlmsTxt(l =>
+    {
+        l.Summary = "ShellDocs is a docs framework for .NET: Markdown pages, live Blazor component previews, search and a static export, in a Blazor Web App.";
+        l.RulesFile = "Llms/agent-rules.md";
+        l.InstallCommandPattern = @"(?m)(?<=^[ \t]*)dotnet (?:tool install -g ShellDocs\.CLI|add package ShellDocs\.\w+)[^\r\n]*";
+    });
+
     o.AddNavLink("Documentation", "/docs/introduction");
     o.AddNavLink("Releases", "https://github.com/shellui-dev/shelldocs/releases");
 
@@ -194,4 +218,5 @@ builder.Services.AddShellDocs(o =>
 <LinkCard Title="Component reference" Description="Every shipped primitive." Href="/docs/components/callout" />
 <LinkCard Title="Documenting a component library" Description="Register and preview your own components." Href="/docs/guides/component-libraries" />
 <LinkCard Title="Deployment" Description="Static export or a .NET host." Href="/docs/guides/deployment" />
+<LinkCard Title="AI agents (llms.txt)" Description="Docs that coding agents can read." Href="/docs/guides/llms-txt" />
 </CardGrid>
diff --git a/content/docs/getting-started/installation.md b/content/docs/getting-started/installation.md
@@ -59,8 +59,8 @@ dotnet add package ShellDocs.Tokens --prerelease
 <CodeTab Label="PackageReference">
 
 ```xml
-<PackageReference Include="ShellDocs.Components" Version="0.1.15-alpha" />
-<PackageReference Include="ShellDocs.Tokens" Version="0.1.15-alpha" />
+<PackageReference Include="ShellDocs.Components" Version="0.1.17-alpha" />
+<PackageReference Include="ShellDocs.Tokens" Version="0.1.17-alpha" />
 ```
 
 </CodeTab>

diff --git a/content/docs/guides/deployment.md b/content/docs/guides/deployment.md
@@ -1,7 +1,7 @@
 ---
 title: Deployment
 description: Publish as a static site or run on a .NET host. What works where, and a GitHub Pages workflow you can copy.
-order: 6
+order: 7
 ---
 
 # Deployment
@@ -31,7 +31,8 @@ A ShellDocs site is a Blazor Web App. You can run it on a .NET host, or export i
 <TypeRow Name="Redirects" Type="works" Description="Written as redirect pages." />
 <TypeRow Name="Search" Type="works" Description="The index is a file in the export and is ranked in the browser. See below." />
 <TypeRow Name="Collapsing the whole sidebar" Type="works" Description="The desktop collapse button. The choice is remembered across pages." />
-<TypeRow Name="Not-found page" Type="works" Description="Written as 404.html, which most static hosts serve for unknown URLs." />
+<TypeRow Name="Not-found page" Type="works" Description="Written as 404.html, which most static hosts serve for unknown URLs. It names the address the reader asked for." />
+<TypeRow Name="llms.txt and agent files" Type="works" Description="Written into the export as files, with the page actions menu working. See AI agents (llms.txt)." />
 <TypeRow Name="Demos with event handlers" Type="needs a server" Description="A demo that reacts to clicks renders in its initial state and does not respond." />
 </TypeTable>
 
@@ -86,7 +87,7 @@ jobs:
       - uses: actions/setup-dotnet@v4
         with:
           global-json-file: global.json
-      - run: dotnet tool install -g ShellDocs.CLI --version 0.1.15-alpha
+      - run: dotnet tool install -g ShellDocs.CLI --version 0.1.17-alpha
       - run: shelldocs build --site-url https://docs.example.com
       - run: echo "docs.example.com" > publish/CNAME
       - run: touch publish/.nojekyll
@@ -171,4 +172,5 @@ Any platform that runs ASP.NET Core works: a container, a virtual machine, or a
 <LinkCard Title="Redirects" Description="How redirects are written into a static export." Href="/docs/guides/redirects" />
 <LinkCard Title="Search" Description="How search works without a server." Href="/docs/guides/search" />
 <LinkCard Title="Not-found page" Description="DocsNotFound and the 404.html the build writes." Href="/docs/guides/not-found" />
+<LinkCard Title="AI agents (llms.txt)" Description="The llms.txt files the build writes." Href="/docs/guides/llms-txt" />
 </CardGrid>