Add AI-optimized documentation for programmatic usage

README.md

@@ -2,6 +2,35 @@
 
 Documentation for [Doc Detective](https://doc-detective.com) - keep your docs in sync with your product. Always.
 
+## 🤖 For AI Agents and Programmatic Usage
+
+If you're an AI coding agent or need structured information for programmatic usage:
+
+- **[Quick Start for AI Agents](https://doc-detective.com/docs/get-started/quick-start-for-ai)** - Structured guide with JSON examples and common patterns
+- **[API Reference Summary](https://doc-detective.com/docs/get-started/api-reference)** - Complete action parameters, return values, and usage
+- **[Troubleshooting Guide](https://doc-detective.com/docs/get-started/troubleshooting)** - Common errors and solutions with code examples
+
+**Key concepts:**
+- Doc Detective validates documentation by running JSON-defined tests against your product
+- Tests consist of actions (goTo, find, click, screenshot, httpRequest, etc.)
+- Results are output as structured JSON for parsing and automation
+- Ideal for CI/CD pipelines, automated documentation testing, and API validation
+
+**Minimal example:**
+```json
+{
+  "tests": [{
+    "steps": [
+      {"action": "goTo", "url": "https://example.com"},
+      {"action": "find", "selector": "h1"},
+      {"action": "screenshot", "path": "result.png"}
+    ]
+  }]
+}
+```
+
+Run with: `npx doc-detective --input test.spec.json`
+
 ## 🤝 Contributing
 
 We welcome contributions from everyone! Whether you're fixing a typo or writing a complete tutorial, your contribution matters.

docs/get-started/actions/httpRequest.mdx

@@ -14,6 +14,13 @@ import JSONSchemaViewer from "@theme/JSONSchemaViewer";
 
 The `httpRequest` action makes arbitrary HTTP calls, allowing you to interact with and validate APIs or other web services directly within your tests.
 
+**Quick reference:**
+- **Purpose:** Test API endpoints and web services
+- **Common use:** API documentation validation, integration testing
+- **Supported methods:** GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
+- **Validation:** Status codes, response headers, response body
+- **Variables:** Can capture response data for use in subsequent steps
+
 You can specify a basic GET request using a string shorthand or use an object for more complex requests and validation:
 
 - **String Shorthand:** Provide the full URL directly as the value for the `httpRequest` key. This performs a basic GET request to that URL.

docs/get-started/actions/runShell.mdx

@@ -14,6 +14,13 @@ import JSONSchemaViewer from "@theme/JSONSchemaViewer";
 
 The `runShell` action runs a shell command or script on the local machine and evaluates the results, extending Doc Detective's testing capabilities to anything you can script.
 
+**Quick reference:**
+- **Purpose:** Execute shell commands, build scripts, run CLI tools
+- **Common use:** Build documentation, run tests, setup/cleanup, verify CLI outputs
+- **Shell:** Uses system default (cmd on Windows, bash/sh on Unix-like systems)
+- **Validation:** Exit codes, stdout/stderr output
+- **Variables:** Can capture command output for use in subsequent steps
+
 `runShell` uses your device's native shell (`cmd` on Windows, `bash` or other default shell on macOS/Linux) to execute the command in the context of the current user.
 
 You can specify the command directly as a string or use an object for more options: