| name | agui-dotnet-sdk-docs |
| description | Author, update, and validate the AG-UI .NET SDK documentation pages on the docs.ag-ui.com Mintlify site (under docs/). USE FOR: adding or editing a ".NET SDK" docs page (sdk/dotnet/**/*.mdx), wiring it into the docs.json ".NET" nav group and global anchor, running the docs site locally with mintlify dev, previewing/validating rendered .NET pages, checking the .NET sidebar anchor/icon. DO NOT USE FOR: in-repo dotnet markdown such as sdks/dotnet/AGENTS.md or docs/architecture.md (use agui-dotnet-agents-sync); TypeScript/Python docs pages; product code, tests, or wire types.
|
AG-UI .NET SDK — Docs Site Authoring
The published docs at docs.ag-ui.com are a Mintlify project rooted at
docs/. The .NET SDK section is a sibling of the TypeScript and Python
sections. Pages live as .mdx files and are wired into navigation through
docs/docs.json. Get the location or the nav wrong and the page renders nowhere
or breaks the build.
Where .NET docs live
docs/
docs.json # nav + global anchors (single source of truth)
sdk/dotnet/
abstractions/{overview,types,events,multimodal-inputs}.mdx # AGUI.Abstractions
client/{overview,chat-client,transport}.mdx # AGUI.Client
hosting/{overview,endpoints,extensibility}.mdx # AGUI.Hosting.AspNetCore
sdk/js/**, sdk/python/** # sibling sections — the style reference
The .NET nav group in docs.json mirrors the js and python
groups: subgroups named after the packages
(AGUI.Abstractions, AGUI.Client, AGUI.Hosting.AspNetCore) each listing
page paths without the .mdx extension. A global anchor .NET SDK
points at sdk/dotnet/abstractions/overview. (The anchor icon and its CSS
treatment are already set up; this skill is about adding and editing pages, not
the anchor.)
Page conventions (mirror the JS pages)
Study the JS sibling for any page you add — docs/sdk/js/core/overview.mdx,
docs/sdk/js/client/*.mdx — and keep the .NET page parallel in shape.
- Frontmatter:
title (Title Case, e.g. "Overview", "AGUIChatClient")
and description (one line). See docs/sdk/dotnet/abstractions/overview.mdx.
- H1 names the package or type (
# AGUI.Abstractions, # AGUIChatClient),
matching the JS H1 convention (# @ag-ui/core).
- Install fence uses
dotnet add package AGUI.* (JS uses npm install @ag-ui/*).
- Cross-links are root-absolute:
/sdk/dotnet/abstractions/types#runagentinput.
- Mintlify components are in scope (
<Note>, <Card>, <Tip>, etc.) — use the
same ones the surrounding .NET/JS pages use; don't introduce new patterns.
Adding or editing a page
- Create/edit
docs/sdk/dotnet/<group>/<page>.mdx with the frontmatter + H1
conventions above, modeled on the JS sibling page.
- Register it in
docs/docs.json under the correct .NET subgroup, in the
intended order, as "sdk/dotnet/<group>/<page>" (no extension).
- If it is a new top-level entry point, update the
.NET SDK global anchor
href in docs.json too.
- Restart
mintlify dev — docs.json changes are read at startup only.
Local preview
cd docs
npm install
node_modules/.bin/mintlify dev --port=4000
Known, harmless quirks — do not chase these:
docs.json changes need a server restart; .mdx edits hot-reload.- The CLI prints React "invalid hook call" warnings on startup — noise.
- Some pre-existing non-.NET pages have MDX parse errors. If the page you
touched isn't one of them, the error isn't yours — confirm by URL.
Validation loop (Playwright MCP)
Use the generic Playwright-MCP technique from the agui-playwright-validate
skill; the checks below are the docs-specific assertions. Run them against the
running dev server (e.g. http://localhost:4000).
For every .NET page you added or changed:
- Navigate to its localhost URL (
/sdk/dotnet/<group>/<page>).
- Assert HTTP 200 (not a 404 / "page not found" body).
- Assert the rendered H1/heading matches the page's intended title.
- Assert zero console errors for that page load.
For the nav (do once):
5. Confirm the new page appears in the left sidebar under the right .NET
subgroup, in the expected order, and that the page renders (screenshot if a
human needs to eyeball a visual detail).
Cleanup
- Remove any Playwright artifacts (screenshots, traces) the validation produced.
- Stop the
mintlify dev process to free the port when finished.
❌ Critical anti-patterns
- Never add an
.mdx without registering it in docs.json — unregistered
pages don't appear in the nav (and the .NET group is the only correct home
for .NET pages, as a sibling of js/python).
- Never expect a
docs.json edit to hot-reload — restart mintlify dev or
you'll validate stale nav.
- Never invent page structure — mirror the JS sibling's frontmatter, H1,
and component usage instead.
- Don't "fix" the React hook warnings or pre-existing non-.NET MDX errors —
they're out of scope; only the .NET page you touched must render clean.
Files to mine
docs/docs.json (the .NET nav group + the .NET SDK global anchor),
docs/sdk/dotnet/**/*.mdx, the JS reference docs/sdk/js/**/*.mdx,
docs/package.json.
