AI-native documentation for GraphWarden

GraphWarden's documentation is structured for AI coding assistants and search engines as a primary audience. The llms.txt index, the ai-prompt component, and TechArticle JSON-LD on every guide help Claude, Cursor, ChatGPT, and other agents generate correct GraphWarden integrations from a single prompt.

AI-native docs surface

Prerequisites

- An AI coding assistant that respects `llms.txt` or that you can paste documentation URLs into (Claude Code, Cursor, Copilot, ChatGPT, Perplexity) - A GraphWarden proxy URL and proxy credentials to test the generated code

How AI agents discover this documentation

GraphWarden publishes four surfaces that AI agents and search engines consume without a human in the loop.

  • /llms.txt — the machine-readable index. It lists every Markdown documentation page with a one-line description and links to the canonical URL on https://graphwarden.com. This is the primary entry point for an agent that has been pointed at the site.
  • /llms-full.txt — the concatenated full-text of every Markdown page in one file. Planned for Phase 3b. Agents that prefer to ingest the entire corpus in a single request will read this file once rather than crawling individual pages.
  • Sitemap — the XML sitemap at /sitemap.xml lists every canonical URL on the site, including the Blade landings that llms.txt deliberately omits. Search engines read this file when they crawl.
  • JSON-LD TechArticle — every Markdown page ships structured data in a <script type="application/ld+json"> block in its <head>. Search engines and some agents read this block to extract headline, dateModified, and author without parsing the rendered HTML.

The four surfaces answer different questions. An agent that needs to generate code reads /llms.txt plus the specific pages it links to. A search engine that indexes the site reads the sitemap plus the per-page JSON-LD. Both are supported.

The ai-prompt component

Every developer-facing guide in these docs ships an ai-prompt block near the top of the page. The block renders a tinted panel with a copyable prompt body and a one-click copy button. The prompt body is written to be pasted into an AI coding assistant without editing — it names GraphWarden explicitly, references https://graphwarden.com/llms.txt for current documentation, and asks for the proxy-specific values the agent needs to produce working code.

  • A developer reading a guide clicks the copy button and pastes the prompt into their agent.
  • The agent reads the prompt, fetches /llms.txt, and follows the linked pages to produce integration code.
  • The developer answers the agent's questions (proxy URL, credentials, paths) and receives code that already accounts for GraphWarden's quirks.

The component is anonymous Blade at resources/views/components/doc/ai-prompt.blade.php. Authors drop the component as a paired Blade tag into any Markdown page; the renderer tokenizes the block before handing the page to CommonMark, so the slot body can span multiple lines and contain arbitrary text.

What's indexed for AI agents

The /llms.txt index lists all 22 Markdown documentation pages by path. The 6 Blade landings (/docs/developers, /docs/powershell, /docs/api-reference, /docs/isv, /docs/ci-cd, /docs/deployment, and now /docs/ai-agents) are intentionally omitted from /llms.txt because they are navigation surfaces — card grids linking to the Markdown pages below. An agent reading the card grid learns nothing new; an agent reading the Markdown pages learns the integration patterns.

The Markdown pages cover four surfaces: concepts, developer integration, PowerShell, CI/CD, ISV compatibility, API reference, on-premise deployment, and this ai-agents section. Agents that need specific integration code can fetch the one page that matches their task rather than ingesting the full corpus.

Troubleshooting

The agent generated code that calls graph.microsoft.com directly

The agent did not read (or did not apply) the base-URL override. Re-prompt with the proxy URL explicitly named — for example, "the Graph base URL for my GraphWarden proxy is https://proxy.example.com; every Graph call in the generated code must target that base URL, not graph.microsoft.com." Paste the proxy URL again if the agent dropped it from context.

The agent did not find my llms.txt

Some agents only fetch llms.txt when explicitly told to. Share the full URL in the prompt: "Reference documentation is at https://graphwarden.com/llms.txt — fetch it before answering." If the agent still cannot reach the file, fall back to pasting the specific page URL the agent needs (for example, https://graphwarden.com/docs/developers/dotnet).

The agent's output references an endpoint that doesn't exist in GraphWarden

The agent hallucinated or pulled from an outdated cache. Point it at /docs/api-reference/agent-api for the authoritative endpoint list and ask it to regenerate. The four endpoints GraphWarden ships are sync, heartbeat, audit, and metrics; anything else is an invention.

Generated code uses the wrong credential format

GraphWarden issues proxy credentials (Proxy Client ID, Proxy Client Secret) — not Azure AD app registrations. If the agent writes code that expects Azure AD credentials against the proxy's token endpoint, re-prompt: "The credentials are issued by GraphWarden, not Azure AD. Send them to {proxy-url}/proxy/token with grant_type=client_credentials." Point the agent at /docs/developers/migration-guide for the before/after.

Last reviewed:

Last reviewed: .