docs(MAR-394): describe the SDK as a SERP API, a Google News API and an AI search API

README.md

@@ -1,10 +1,17 @@
 # cloro Python SDK
 
-The official Python client for [**cloro**](https://cloro.dev) — one API for
-Google Search and every AI answer engine (ChatGPT, Gemini, Perplexity, Copilot,
-AI Overview, AI Mode). Real-time, structured JSON.
-
-Use the SDK, or [just `curl` it](https://cloro.dev/docs) — same clean response
+The official Python SDK for [**cloro**](https://cloro.dev): a
+[SERP API](https://cloro.dev/serp-api/) for Google Search, a Google News API
+and an AI search API that returns the answers of ChatGPT, Perplexity, Gemini,
+Copilot, Google AI Overview and AI Mode as real-time, structured JSON with
+sources. Use it in scripts, data pipelines, agents and RAG pipelines.
+
+For agents there is also a hosted MCP server at `https://mcp.cloro.dev/mcp`
+for Claude, Cursor and any MCP client
+([setup](https://cloro.dev/docs/integrations/mcp),
+[source](https://github.com/cloro-dev/mcp-server)).
+
+Use the SDK, or [just `curl` it](https://cloro.dev/docs): same clean response
 either way. The SDK adds typed methods, sensible retries, and a polling helper
 for the async task queue so you don't hand-roll it.
 
@@ -54,8 +61,31 @@ client.monitor.google(query="best crm", country="US", pages=1)
 client.monitor.google_news(query="acme corp", country="US")
 ```
 
-Pass `include={...}` to request extra formats — `markdown`, `html`,
-`searchQueries`, `shopping`, and more, depending on the engine.
+Pass `include={...}` to request extra formats: `markdown`, `html`,
+`searchQueries`, `shopping`, and more, depending on the engine. On ChatGPT,
+`searchQueries` is empty unless you also pass `legacy=True` (best effort).
+
+## Google Search results as JSON
+
+`client.monitor.google` returns the parsed results page: organic results,
+People Also Ask, ads, local results and more. One request covers up to 10
+pages; each page after the first adds 2 credits. Add `include={"html": True}`
+for links to the raw HTML of each page, at no extra cost.
+
+```python
+res = client.monitor.google(query="best crm", country="US", pages=2, include={"html": True})
+
+for item in res["result"]["organicResults"]:
+    print(item["position"], item["title"], item["link"])
+
+print(res["result"]["html"])  # one URL per page; each expires after 24 hours
+```
+
+Add `include={"aioverview": True}` to get Google's AI Overview and its sources
+in the same response (+2 credits).
+
+`client.monitor` calls are sync requests, so each adds a +2 credit surcharge
+on top of the base cost and any add-ons; the async task queue below does not.
 
 ## Async task queue
 
@@ -156,9 +186,9 @@ client.states()                # US states for location-targeted Google
 
 ## Links
 
-- [cloro.dev](https://cloro.dev) — the hosted SERP + AI answer-engine API
-- [SERP API](https://cloro.dev/serp-api/) — the Google Search endpoint this SDK wraps
-- [Python guide](https://cloro.dev/integrations/python/) — quickstart, recipes, and production patterns
+- [cloro.dev](https://cloro.dev): the hosted SERP + AI answer-engine API
+- [SERP API](https://cloro.dev/serp-api/): the Google Search endpoint this SDK wraps
+- [Python guide](https://cloro.dev/integrations/python/): quickstart, recipes, and production patterns
 - [Docs](https://cloro.dev/docs) and [API reference (OpenAPI)](https://cloro.dev/docs/api-reference/openapi.json)
 - [Pricing](https://cloro.dev/pricing/) · [Dashboard](https://dashboard.cloro.dev/)
 - TypeScript SDK: [cloro-node](https://github.com/cloro-dev/cloro-node)