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

1. Create/edit docs/sdk/dotnet/<group>/<page>.mdx with the frontmatter + H1 conventions above, modeled on the JS sibling page.
2. Register it in docs/docs.json under the correct .NET subgroup, in the intended order, as "sdk/dotnet/<group>/<page>" (no extension).
3. If it is a new top-level entry point, update the .NET SDK global anchor href in docs.json too.
4. Restart mintlify dev — docs.json changes are read at startup only.

Local preview

cd docs
npm install                       # first run only; installs Mintlify locally
node_modules/.bin/mintlify dev --port=4000   # or: npm run dev (defaults to 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:

1. Navigate to its localhost URL (/sdk/dotnet/<group>/<page>).
2. Assert HTTP 200 (not a 404 / "page not found" body).
3. Assert the rendered H1/heading matches the page's intended title.
4. 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

1. 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).
2. Never expect a docs.json edit to hot-reload — restart mintlify dev or you'll validate stale nav.
3. Never invent page structure — mirror the JS sibling's frontmatter, H1, and component usage instead.
4. 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.