docs: consolidate agent playbook and LLM reference pages

[openoms]

Summary

The "API Reference for LLMs" and "AI Agent API Playbook" pages had overlapping content. This PR gives each a clear audience:

• AI Agent API Playbook — stays concise for machine consumption. Added a "Discovery" section pointing to llms.txt and a link to the human guide in Related Reading.
• Building with AI Agents (was "API Reference for LLMs") — rewritten as a human-facing developer guide:
  • llms.txt discovery section
  • Compact schema download table (replaces verbose headings)
  • 3 practical integration patterns: framework-agnostic system prompt, Python with httpx, Node.js (replaces outdated LangChain/OpenAI examples)

Sidebar reorder

Errors > Postman > API reference (external) > Building with AI Agents > AI Agent API Playbook

The playbook sits last as the capstone agent-facing page.

Files changed

• docs/api/agent-playbook.md — added Discovery section + cross-link
• docs/api/llm-api-reference.md — full rewrite as human-facing guide
• sidebars.js — reordered entries

[openoms]

@blink-claw-bot review

[Copilot]

Pull request overview

This PR consolidates overlapping LLM/agent documentation by separating content into an agent-facing playbook and a developer-facing “Building with AI Agents” guide, and updates navigation ordering accordingly.

Changes:

• Rewrites llm-api-reference into a developer guide with llms.txt discovery, schema downloads, and updated integration patterns.
• Adds a Discovery section + cross-linking in the AI Agent API Playbook.
• Reorders the API docs sidebar entries to match the new intended reading flow.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
sidebars.js	Reorders sidebar items so the developer guide precedes the agent playbook.
docs/api/llm-api-reference.md	Reframes page as a human-facing integration guide; adds discovery, downloads table, and new Python/Node patterns.
docs/api/agent-playbook.md	Adds llms.txt discovery pointer and links back to the developer guide.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[blink-claw-bot]

Excellent consolidation work! ✅

This PR effectively addresses the overlapping content issue and creates a cleaner information architecture. Here's my detailed review:

✅ Clarity & Structure

• Much improved title: "Building with AI Agents" clearly targets developers vs. the previous LLM-centric approach
• Logical flow: Discovery → Schema downloads → Integration patterns → Resources
• Clear audience separation: Explicit tip directing agents to the playbook instead

✅ Content Quality

• Practical integration patterns: System prompt, Python, Node.js examples cover the most common use cases
• Discovery section addition: The llms.txt reference creates a proper entry point for agents
• Technical accuracy: Verified links are accessible (llms.txt, schema files) and content matches current API structure

✅ Information Architecture

• Eliminates duplication: No longer two competing pages with overlapping agent guidance
• Better sidebar ordering: Moving specialized topics (LLM reference, agent playbook) to the bottom makes sense
• Cross-references updated: Agent playbook now properly links to the consolidated guide

✅ Developer Experience

• Framework-agnostic approach: Shows the pattern works with any LLM provider
• Copy-paste ready examples: Practical code snippets developers can immediately use
• Reduced confusion: Single source of truth for AI integration guidance

Minor Observations

• The content reduction (101 lines removed, 81 added) demonstrates effective consolidation
• Maintains consistent tone throughout both modified files
• All referenced resources are properly accessible

Great work consolidating these overlapping resources into a more coherent developer experience! 🚀

🤖 Review by claude-sonnet-4 via Blink-Claw-Bot