Add agent discovery directive and reference page

[jordanurbs]

Summary

• agent-reference.html (new): Static, token-optimized single-page API reference for AI agents — every endpoint, model, code example, and pitfall in one file with zero framework overhead.
• docs.json: Add dismissible banner on every page, sidebar link (with robot icon) in the Overview group, and ai-agent-reference meta tags.
• llms.txt: Prepend AGENT NOTICE blockquote directing agents to docs.venice.ai/agent-reference.html.
• about-venice.mdx: Add <Note> callout at the top of the landing page.
• ai-agents.mdx: Add "Agent API Reference" section at the top of the AI Agents guide.

Why

AI agents scraping docs.venice.ai currently crawl dozens of Mintlify pages to piece together API knowledge. This PR adds a single static HTML page at docs.venice.ai/agent-reference.html and makes it discoverable through five layers:

1. llms.txt — the standard that Cursor, Claude Code, LangChain, OpenClaw, etc. check first
2. Banner — visible on every page to both scrapers and humans
3. Sidebar — persistent navigation link with robot icon
4. Landing page callout — first body content agents see on the root page
5. Meta tags — low-cost signal for metadata-first agents

Test plan

• Verify agent-reference.html loads at docs.venice.ai/agent-reference.html as static HTML (no Mintlify wrapper)
• Verify llms.txt shows the AGENT NOTICE blockquote before the existing description
• Verify the banner appears at the top of every docs page and is dismissible
• Verify "Agent API Reference" appears in the sidebar under Overview with a robot icon
• Verify the <Note> callout renders on /overview/about-venice
• Verify the "Agent API Reference" section appears at the top of /overview/guides/ai-agents
• Verify all links resolve to docs.venice.ai/agent-reference.html

Made with Cursor

[sabrinaaquino]

Requesting changes for now. I agree with the goal of making the docs more agent-friendly, but I don’t think this implementation is ready to merge yet.

My main concern is that this introduces too many competing agent entrypoints instead of defining one clear canonical path. I also don’t think a dedicated agent-reference.html is the right long-term fix here, especially if it can drift from the actual docs/spec and create a second source of truth.

I found examples where the new agent-facing content already appears inconsistent with the current docs/spec. For example, it says image generation is not OpenAI-compatible even though we already document POST /images/generations as an OpenAI-compatible endpoint, and it also hard-codes model counts/recommendations and endpoint behavior that are likely to drift over time. I also saw method/behavior details in the page that made me nervous about pointing agents to it as a canonical reference.

Separately, I don’t think we should degrade the normal docs UX for this. The banner, visible note, sidebar link, and other user-facing agent promos feel like the wrong tradeoff.

I’d rather we step back and simplify the approach:

• define one canonical agent entrypoint
• keep agent discovery low-clutter for normal users
• rely on llms.txt plus the existing docs/OpenAPI as source of truth
• avoid adding a separate HTML artifact unless we’re committed to maintaining it as a first-class surface

Happy to revisit once the approach is tighter and the current inconsistencies are resolved.

[joshua-mo-143]

Requesting changes for now. I agree with the goal of making the docs more agent-friendly, but I don’t think this implementation is ready to merge yet.

My main concern is that this introduces too many competing agent entrypoints instead of defining one clear canonical path. I also don’t think a dedicated agent-reference.html is the right long-term fix here, especially if it can drift from the actual docs/spec and create a second source of truth.

I found examples where the new agent-facing content already appears inconsistent with the current docs/spec. For example, it says image generation is not OpenAI-compatible even though we already document POST /images/generations as an OpenAI-compatible endpoint, and it also hard-codes model counts/recommendations and endpoint behavior that are likely to drift over time. I also saw method/behavior details in the page that made me nervous about pointing agents to it as a canonical reference.

Separately, I don’t think we should degrade the normal docs UX for this. The banner, visible note, sidebar link, and other user-facing agent promos feel like the wrong tradeoff.

I’d rather we step back and simplify the approach:

* define one canonical agent entrypoint

* keep agent discovery low-clutter for normal users

* rely on `llms.txt` plus the existing docs/OpenAPI as source of truth

* avoid adding a separate HTML artifact unless we’re committed to maintaining it as a first-class surface

Happy to revisit once the approach is tighter and the current inconsistencies are resolved.

+1'ing this. If Mintlify already has standard procedures for handling llms.txt and such, it can be inferred that agents will probably be expecting us to follow those procedures.

Unrelated to this PR, but related to the core issue that we're solving here: we should probably figure out a way to render those model names in the .md files that Mintlify seems to serve. It looks like on the Markdown that nothing actually appears, so unless the agents know to visit the html page and wait for the entire doc to load they can't see what models we have. You can see what I mean here: https://docs.venice.ai/models/text.md