Add testable documentation with inline code examples

.changeset/testable-docs-snippets.md

@@ -0,0 +1,28 @@
+---
+"adcontextprotocol": minor
+---
+
+Add testable documentation infrastructure and improve library discoverability
+
+**Library Discoverability:**
+- Added prominent "Client Libraries" section to intro.mdx with NPM badge and installation links
+- Updated README.md with NPM package badge and client library installation instructions
+- Documented Python client development status (in development, use MCP SDK directly)
+- Added links to NPM package, PyPI (future), and GitHub repositories
+
+**Documentation Snippet Testing:**
+- Created comprehensive snippet validation test suite (`tests/snippet-validation.test.js`)
+- Extracts code blocks from all documentation files (.md and .mdx)
+- Tests JavaScript, TypeScript, Python, and Bash (curl) examples
+- Snippets marked with `test=true` or `testable` are automatically validated
+- Integration with test suite via `npm run test:snippets` and `npm run test:all`
+- Added contributor guide for writing testable documentation snippets
+
+**What this enables:**
+- Documentation examples stay synchronized with protocol changes
+- Broken examples are caught in CI before merging
+- Contributors can confidently update examples knowing they'll be tested
+- Users can trust that documentation code actually works
+
+**For contributors:**
+See `docs/contributing/testable-snippets.md` for how to write testable documentation examples.

.gitguardian.yaml

@@ -0,0 +1,13 @@
+version: 2
+
+# GitGuardian configuration for AdCP repository
+# This file configures what GitGuardian should scan and what to ignore
+
+# Ignore test tokens that are documented and meant to be public
+matches-ignore:
+  - name: Test Agent Authentication Token
+    match: 1v8tAhASaUYYp4odoQ1PnMpdqNaMiTrCRqYo9OJp6IQ
+    comment: |
+      This is a documented test token for the public test agent at
+      https://test-agent.adcontextprotocol.org/mcp. It's intentionally
+      included in documentation examples and has no production access.

.github/workflows/check-testable-snippets.yml

@@ -0,0 +1,32 @@
+name: Check Testable Snippets
+
+on:
+  pull_request:
+    paths:
+      - 'docs/**/*.md'
+      - 'docs/**/*.mdx'
+
+jobs:
+  check-snippets:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Need full history for diff
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+
+      - name: Check for untested code snippets
+        run: |
+          git fetch origin ${{ github.base_ref }}
+          git diff origin/${{ github.base_ref }}...HEAD --name-only | grep -E '\.(md|mdx)$' > changed_files.txt || true
+
+          if [ -s changed_files.txt ]; then
+            echo "📋 Checking documentation changes for testable snippets..."
+            node scripts/check-testable-snippets.js
+          else
+            echo "✓ No documentation files changed"
+          fi

CLAUDE.md

@@ -6,6 +6,27 @@ This guide helps AI assistants understand the AdCP project structure and maintai
 
 The Advertising Context Protocol (AdCP) is an open standard for AI-powered advertising workflows. It provides a unified interface for media buying across diverse advertising platforms.
 
+## Documentation Framework
+
+**CRITICAL**: This project uses TWO documentation systems:
+
+1. **Mintlify** - Primary documentation platform
+   - All documentation in `docs/` directory
+   - Markdown/MDX files served by Mintlify
+   - Uses Mintlify-specific components (`<CodeGroup>`, not Docusaurus `<Tabs>`)
+   - Run with: `mintlify dev` (should use conductor port, not 3000)
+
+2. **Docusaurus** - Legacy/backwards compatibility only
+   - Used for homepage
+   - Used to serve JSON schemas at `/schemas/` endpoints
+   - Will be migrated away from eventually
+   - DO NOT use Docusaurus components in documentation files
+
+**When editing documentation:**
+- ✅ Use Mintlify `<CodeGroup>` for multi-language examples
+- ❌ DO NOT use Docusaurus `import Tabs from '@theme/Tabs'`
+- ❌ DO NOT use `<Tabs>` or `<TabItem>` components
+
 ## Documentation Standards
 
 ### Protocol Specification vs Implementation
@@ -42,6 +63,79 @@ Implementation details can be mentioned as:
 - Write for an audience implementing the protocol, not using a specific implementation
 - Keep examples generic and illustrative
 
+### Testable Documentation
+
+**IMPORTANT**: All code examples in documentation should be testable when possible.
+
+**How to mark pages as testable**:
+
+Add `testable: true` to the frontmatter of pages where all code examples should be tested:
+
+```markdown
+---
+title: get_products
+sidebar_position: 1
+testable: true
+---
+
+# get_products
+
+...code examples here (no test=true needed in individual blocks)...
+```
+
+**Key principles**:
+1. **Page-level flag** - Use `testable: true` in frontmatter to mark entire page as testable
+2. **Tab titles** - The text after the language becomes the tab title (e.g., "JavaScript", "Python", "CLI")
+3. **Complete examples** - All code on testable pages must be complete and runnable
+4. **Use test credentials** - Use the public test agent credentials in examples
+
+**Supported languages**:
+- `javascript` / `typescript` - Runs with Node.js ESM modules
+- `python` - Runs with Python 3.11+
+- `bash` - Supports `curl`, `npx`, and `uvx` commands
+
+**What gets tested**:
+- All code blocks on pages with `testable: true` frontmatter
+- Code executes without errors
+- API calls succeed (or fail as expected)
+- Output matches expectations
+
+**When NOT to mark page as testable**:
+- Pages with incomplete code fragments
+- Conceptual examples or pseudocode
+- Browser-only code examples
+- Code requiring user interaction
+- Mixed testable and non-testable examples (use separate pages)
+
+**Example testable page**:
+
+```markdown
+---
+title: get_products
+testable: true
+---
+
+# get_products
+
+<CodeGroup>
+
+\`\`\`javascript JavaScript
+import { ADCPMultiAgentClient } from '@adcp/client';
+const client = new ADCPMultiAgentClient([...]);
+\`\`\`
+
+\`\`\`python Python
+from adcp import ADCPMultiAgentClient
+\`\`\`
+
+</CodeGroup>
+```
+
+**Running tests**:
+```bash
+node tests/snippet-validation.test.js
+```
+
 ## JSON Schema Maintenance
 
 ### Schema-Documentation Consistency

README.md

@@ -4,6 +4,7 @@
 
 [![GitHub stars](https://img.shields.io/github/stars/adcontextprotocol/adcp?style=social)](https://github.com/adcontextprotocol/adcp)
 [![Documentation](https://img.shields.io/badge/docs-adcontextprotocol.org-blue)](https://adcontextprotocol.org)
+[![npm version](https://img.shields.io/npm/v/@adcp/client)](https://www.npmjs.com/package/@adcp/client)
 [![MCP Compatible](https://img.shields.io/badge/MCP-compatible-green)](https://modelcontextprotocol.io)
 
 > **AdCP revolutionizes advertising automation by providing a single, AI-powered protocol that works across all major advertising platforms.**
@@ -53,6 +54,22 @@ Execute and optimize media buys programmatically across platforms.
 
 ## Quick Start
 
+### Install Client Libraries
+
+#### JavaScript/TypeScript
+```bash
+npm install @adcp/client
+```
+- **NPM Package**: [@adcp/client](https://www.npmjs.com/package/@adcp/client)
+- **GitHub**: [adcp-client](https://github.com/adcontextprotocol/adcp-client)
+
+#### Python
+```bash
+pip install adcp
+```
+- **PyPI Package**: [adcp](https://pypi.org/project/adcp/)
+- **GitHub**: [adcp-python](https://github.com/adcontextprotocol/adcp-python)
+
 ### For Platform Providers
 
 Implement AdCP to enable AI-powered workflows for your customers:

docs/contributing/testable-examples-demo.md

@@ -0,0 +1,84 @@
+---
+testable: true
+---
+
+# Testable Documentation Examples
+
+This page demonstrates the testable documentation feature with complete, working code examples that execute against the live test agent.
+
+## JavaScript Example
+
+### List Creative Formats
+
+```javascript
+import { testAgent } from '@adcp/client/testing';
+
+const result = await testAgent.listCreativeFormats({});
+
+console.log(`✓ Found ${result.data?.formats?.length || 0} creative formats`);
+```
+
+## Python Example
+
+### List Creative Formats
+
+```python
+import asyncio
+from adcp import test_agent
+
+async def list_formats():
+    result = await test_agent.simple.list_creative_formats()
+    print(f"✓ Found {len(result.formats)} supported creative formats")
+
+asyncio.run(list_formats())
+```
+
+## CLI Example
+
+### Using uvx (Python CLI)
+
+```bash
+uvx adcp \
+  https://test-agent.adcontextprotocol.org/mcp \
+  list_creative_formats \
+  '{}' \
+  --auth 1v8tAhASaUYYp4odoQ1PnMpdqNaMiTrCRqYo9OJp6IQ
+```
+
+## How Testable Documentation Works
+
+When `testable: true` is set in the frontmatter, ALL code blocks on this page are extracted and executed during testing.
+
+### Running Tests
+
+```bash
+# Run all tests including snippet validation
+npm run test:all
+```
+
+### Requirements for Testable Pages
+
+Every code block must:
+- Be complete and self-contained
+- Import all required dependencies
+- Execute without errors
+- Produce output confirming success
+
+### When to Mark Pages as Testable
+
+Mark a page `testable: true` ONLY when:
+- ALL code blocks are complete working examples
+- No code fragments or incomplete snippets
+- All examples use test agent credentials
+- Dependencies are installed (`@adcp/client`, `adcp`)
+
+### When NOT to Mark Pages as Testable
+
+Do NOT mark pages testable that contain:
+- Code fragments showing patterns
+- Incomplete examples
+- Conceptual pseudocode
+- Examples requiring production credentials
+- Mixed testable and non-testable content
+
+See [Testable Snippets Guide](./testable-snippets.md) for complete documentation.