openclaw-crawleo-skill 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Crawleo OpenClaw Skill contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,236 @@
+# Crawleo OpenClaw Skill
+
+A self-contained OpenClaw skill package for Crawleo web intelligence capabilities: Bing-powered web search, Google Search, Google Maps place search, URL crawling/content extraction, and Headful Browser crawling for protected or heavily dynamic sites.
+
+## Status
+
+This package is contract-backed and includes offline-tested REST wrapper helpers for every documented Crawleo endpoint in this milestone:
+
+- `/search`
+- `/google-search`
+- `/google-maps`
+- `/crawl`
+- `/headful-browser`
+
+Live Crawleo calls require `CRAWLEO_API_KEY`. Default verification is offline and must not call Crawleo, require credentials, or consume credits.
+
+Current source of truth:
+
+- Machine-readable endpoint contract: `contracts/crawleo-endpoints.json`
+- Human-readable endpoint contract: `contracts/crawleo-endpoints.md`
+- Endpoint coverage checklist: `contracts/coverage-checklist.md`
+- Final assembly report: `contracts/final-assembly-report.md`
+- Skill metadata: `skill.json`
+- Skill instructions: `SKILL.md`
+
+## Installation and Setup
+
+Use Node.js 18 or newer.
+
+```bash
+npm install
+```
+
+This package currently has no runtime dependencies.
+
+For live Crawleo calls, configure `CRAWLEO_API_KEY` in the environment where OpenClaw or Node runs. The key is sent with Crawleo's documented `x-api-key` header by default.
+
+Never print, echo, log, serialize, commit, or include the API key in examples, errors, test output, or debug output. The wrapper errors are designed to redact configured secrets before serialization.
+
+## Basic Usage
+
+```js
+import { createCrawleoClient } from 'openclaw-crawleo-skill';
+
+const client = createCrawleoClient({
+  apiKey: process.env.CRAWLEO_API_KEY
+});
+
+const results = await client.search({
+  query: 'ai agents',
+  max_pages: 1
+});
+```
+
+For tests and offline examples, inject `fetch` so no network request is made:
+
+```js
+import { createCrawleoClient } from 'openclaw-crawleo-skill';
+
+const client = createCrawleoClient({
+  apiKey: 'test-key',
+  fetch: async (url, init) => ({
+    ok: true,
+    status: 200,
+    headers: new Map([['content-type', 'application/json']]),
+    async text() {
+      return JSON.stringify({ url: url.toString(), method: init.method });
+    }
+  })
+});
+
+await client.crawl({ urls: ['https://example.com'], markdown: true });
+```
+
+## Wrapper API
+
+Create one client and call endpoint-specific methods with endpoint parameters.
+
+### Bing-powered web search
+
+```js
+await client.search({
+  query: 'machine learning',
+  max_pages: 1,
+  device: 'desktop',
+  markdown: true
+});
+```
+
+### Google Search
+
+```js
+await client.googleSearch({
+  q: 'best CRM software',
+  gl: 'us',
+  hl: 'en',
+  type: 'search',
+  num: 10
+});
+```
+
+### Google Maps
+
+```js
+await client.googleMaps({
+  q: 'restaurants in Paris',
+  hl: 'fr'
+});
+```
+
+### URL crawling and extraction
+
+```js
+await client.crawl({
+  urls: ['https://example.com'],
+  markdown: true,
+  render_js: false
+});
+```
+
+### Headful Browser crawling
+
+```js
+await client.headfulBrowser({
+  urls: 'https://example.com',
+  country: 'us',
+  output_format: 'markdown',
+  screenshot: false
+});
+```
+
+Top-level wrapper functions are also exported for advanced composition. They accept a configured client object plus endpoint parameters, not raw credentials:
+
+```js
+import { createCrawleoClient, googleSearch } from 'openclaw-crawleo-skill';
+
+const client = createCrawleoClient({ apiKey: process.env.CRAWLEO_API_KEY });
+await googleSearch(client, { q: 'AI agents', type: 'news' });
+```
+
+## Covered Crawleo Capabilities
+
+| REST Endpoint | MCP Tool | Wrapper Method | Required Params | Documented Cost / Notes |
+|---|---|---|---|---|
+| `/search` | `search_web` | `client.search` | `query` | 10 credits per page via `max_pages`; example-only `count` behavior is not specified in Crawleo docs. |
+| `/google-search` | `google_search` | `client.googleSearch` | `q` | 10 credits per request; documented endpoint is absent from the local OpenAPI snapshot. |
+| `/google-maps` | `google_maps` | `client.googleMaps` | `q` | Endpoint docs say 30 credits per request; MCP overview says 10 credits per request. Preserve this as a source conflict. |
+| `/crawl` | `crawl_web` | `client.crawl` | `urls` | 1 credit per URL when `render_js=false`; 10 credits per URL when `render_js=true`. |
+| `/headful-browser` | `headful_browser` | `client.headfulBrowser` | `urls` | 50 credits per URL; failed requests cost 0 credits; documented endpoint is absent from the local OpenAPI snapshot. |
+
+Validation is intentionally bounded to the contract. The wrapper checks required parameters and explicit documented enums such as `device`, Google Search `type` and `tbs`, and Headful Browser `output_format`. It does not invent undocumented limits.
+
+## Error Handling
+
+The package exports `CrawleoError` and `CRAWLEO_ERROR_CODES` for stable diagnostics.
+
+```js
+import { CrawleoError, CRAWLEO_ERROR_CODES } from 'openclaw-crawleo-skill';
+
+try {
+  await client.googleSearch({ q: 'AI agents', type: 'videos' });
+} catch (error) {
+  if (error instanceof CrawleoError) {
+    console.error(error.toJSON());
+  }
+}
+```
+
+Stable error codes include:
+
+| Code | Meaning |
+|---|---|
+| `CRAWLEO_CONFIG_MISSING_API_KEY` | Live call attempted without an API key. |
+| `CRAWLEO_CONFIG_MISSING_FETCH` | No `fetch` implementation is available. |
+| `CRAWLEO_VALIDATION_ERROR` | Wrapper input failed documented required-field or enum validation. |
+| `CRAWLEO_HTTP_BAD_REQUEST` | Crawleo returned HTTP 400. |
+| `CRAWLEO_HTTP_AUTH` | Crawleo returned HTTP 401. |
+| `CRAWLEO_HTTP_PAYMENT_REQUIRED` | Crawleo returned HTTP 402, typically insufficient credits. |
+| `CRAWLEO_HTTP_FORBIDDEN` | Crawleo returned HTTP 403, such as inactive account or expired subscription. |
+| `CRAWLEO_HTTP_RATE_LIMIT` | Crawleo returned HTTP 429. |
+| `CRAWLEO_HTTP_UPSTREAM` | Crawleo returned a 5xx or otherwise unmapped HTTP failure. |
+| `CRAWLEO_RESPONSE_MALFORMED_JSON` | Crawleo returned a successful response that could not be parsed as JSON. |
+| `CRAWLEO_TRANSPORT_ERROR` | Fetch failed before an HTTP response was received. |
+
+`CrawleoError.toJSON()` includes structured fields such as `code`, `endpoint`, `status`, `field`, and redacted `details`. It must not include raw API key values.
+
+## Offline Verification
+
+Run the default offline checks:
+
+```bash
+npm test
+npm run verify:contracts
+npm run verify:examples
+npm run verify:scaffold
+```
+
+These commands must not call `https://api.crawleo.dev`, require `CRAWLEO_API_KEY`, or consume Crawleo credits.
+
+Optional live smoke tests are available but are disabled unless both variables are present:
+
+```bash
+CRAWLEO_API_KEY=... CRAWLEO_ENABLE_LIVE_TESTS=1 npm run test:live
+```
+
+Without both variables, `npm run test:live` skips the live test and exits successfully.
+
+## Optional Crawleo MCP Companion
+
+Crawleo documents an MCP endpoint at:
+
+```text
+https://api.crawleo.dev/mcp
+```
+
+This package uses REST wrappers as the primary execution path. MCP setup is optional companion context, not the primary implementation path for this milestone.
+
+## Contract and Ambiguity Policy
+
+Use `contracts/crawleo-endpoints.json` as the implementation source of truth. Crawleo endpoint-specific docs take precedence over the local OpenAPI snapshot when the OpenAPI snapshot omits a documented endpoint.
+
+When a default, limit, parameter, error table, or response field is unclear, write `not specified in Crawleo docs` rather than inventing behavior.
+
+Known source issues preserved from the contract inventory:
+
+- `/google-search` and `/headful-browser` are documented by endpoint docs but absent from the local OpenAPI snapshot.
+- Google Maps cost differs by source: endpoint docs say 30 credits per request; MCP overview says 10 credits per request.
+- `/search` examples include `count`, but the visible parameter table does not document it.
+
+## Development Roadmap
+
+- S02: package scaffold, metadata, README, and offline scaffold verification.
+- S03: Crawleo REST client and endpoint wrappers with offline tests.
+- S04: complete user documentation, examples, and endpoint coverage checklist.
+- S05: offline wrapper tests and optional live-test gating.
+- S06: final package integration proof.

package/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: crawleo
+description: Use when OpenClaw needs Crawleo-powered web search, Google Search SERP data, Google Maps place data, URL crawling/content extraction, or headful browser crawling through the Crawleo REST API.
+---
+
+# Crawleo OpenClaw Skill
+
+Use this skill when OpenClaw needs Crawleo-powered live web search, Google Search SERP data, Google Maps place data, URL crawling/content extraction, or headful browser crawling for protected and highly dynamic sites.
+
+## Current Implementation Status
+
+This repository now includes offline-tested Crawleo REST wrapper helpers for all five documented endpoints. Live Crawleo calls require `CRAWLEO_API_KEY`; user-facing examples and optional live verification are expanded in later slices. Do not claim live behavior was verified unless an explicitly enabled live test has run.
+
+## Source of Truth
+
+Use `contracts/crawleo-endpoints.json` as the machine-readable endpoint contract, `contracts/crawleo-endpoints.md` as the human-readable contract, and `contracts/coverage-checklist.md` as the endpoint-to-wrapper/test/example coverage checklist. These files cover:
+
+- `/search` mapped to MCP tool `search_web`
+- `/google-search` mapped to MCP tool `google_search`
+- `/google-maps` mapped to MCP tool `google_maps`
+- `/crawl` mapped to MCP tool `crawl_web`
+- `/headful-browser` mapped to MCP tool `headful_browser`
+
+Crawleo endpoint-specific docs take precedence over the local OpenAPI snapshot when sources conflict. If a default, limit, response field, error table, or parameter is unclear, write `not specified in Crawleo docs` rather than inventing behavior.
+
+## Authentication and Secret Handling
+
+Live Crawleo REST calls require `CRAWLEO_API_KEY`. Send it with Crawleo's documented `x-api-key` header by default. Crawleo also documents `Authorization: Bearer YOUR_API_KEY` as an alternate authentication style.
+
+Create a client with `createCrawleoClient({ apiKey: process.env.CRAWLEO_API_KEY })`, then call `client.search`, `client.googleSearch`, `client.googleMaps`, `client.crawl`, or `client.headfulBrowser` with endpoint parameters from `contracts/crawleo-endpoints.json`.
+
+Never print, echo, log, persist, or include API key values in errors, examples, test output, or debug output.
+
+## Offline-First Behavior
+
+Default commands, examples, and tests must be offline-safe. They must not call `https://api.crawleo.dev`, require `CRAWLEO_API_KEY`, or consume Crawleo credits unless explicitly marked as live tests.
+
+Live tests must require both:
+
+1. `CRAWLEO_API_KEY`
+2. `CRAWLEO_ENABLE_LIVE_TESTS=1`
+
+Run optional live verification with:
+
+```bash
+CRAWLEO_API_KEY=... CRAWLEO_ENABLE_LIVE_TESTS=1 npm run test:live
+```
+
+Without both variables, the live test skips safely and exits 0.
+
+## Endpoint Use Guidance
+
+- Use `/search` / `search_web` for Bing-powered web search with optional auto-crawling and content extraction for LLM/RAG workflows.
+- Use `/google-search` / `google_search` for Google SERP data, including web, news, images, places, shopping, knowledge graph, People Also Ask, related searches, and answer boxes.
+- Use `/google-maps` / `google_maps` for structured place/business/landmark data from Google Maps.
+- Use `/crawl` / `crawl_web` for direct URL crawling and content extraction. Try this before headful browser to reduce credit usage.
+- Use `/headful-browser` / `headful_browser` only when standard crawling is blocked or a headed browser/screenshot path is required. Crawleo docs say this costs 50 credits per URL and failed requests cost 0 credits.
+
+## Verification
+
+Run offline verification with:
+
+```bash
+npm test
+npm run verify:contracts
+npm run verify:examples
+npm run verify:scaffold
+```
+
+At this stage, `npm run verify:scaffold` proves the self-contained package files exist, point to the Crawleo contract inventory, and export the runtime wrapper surface. Later slices add richer examples, documentation, and optional live-test gating.

package/contracts/coverage-checklist.md

@@ -0,0 +1,22 @@
+# Crawleo Endpoint Coverage Checklist
+
+This checklist maps the documented Crawleo surface to this OpenClaw skill package. It is intended for downstream documentation, test, and final assembly verification.
+
+| REST Endpoint | MCP Tool | Contract Entry | Wrapper Method | README Coverage | Example Coverage | Test Coverage | Notes |
+|---|---|---|---|---|---|---|---|
+| `/search` | `search_web` | `contracts/crawleo-endpoints.json` id `search` | `client.search` / `search(client, params)` | Basic usage, wrapper API, covered capabilities table | `examples/offline-fake-fetch.js` | `test/wrapper-fixtures.test.js`, `test/endpoints.test.js`, `test/client.test.js`, `test/errors.test.js` | `count` appears in examples but is not in the visible parameter table; keep as not specified in Crawleo docs. |
+| `/google-search` | `google_search` | `contracts/crawleo-endpoints.json` id `google_search` | `client.googleSearch` / `googleSearch(client, params)` | Wrapper API and covered capabilities table | `examples/offline-fake-fetch.js` | `test/wrapper-fixtures.test.js`, `test/endpoints.test.js`, `test/errors.test.js` | Documented by endpoint docs but absent from the local OpenAPI snapshot. |
+| `/google-maps` | `google_maps` | `contracts/crawleo-endpoints.json` id `google_maps` | `client.googleMaps` / `googleMaps(client, params)` | Wrapper API and covered capabilities table | `examples/offline-fake-fetch.js` | `test/wrapper-fixtures.test.js`, `test/endpoints.test.js`, `test/errors.test.js` | Cost differs by source: endpoint docs say 30 credits per request; MCP overview says 10 credits per request. |
+| `/crawl` | `crawl_web` | `contracts/crawleo-endpoints.json` id `crawl` | `client.crawl` / `crawl(client, params)` | Wrapper API and covered capabilities table | `examples/offline-fake-fetch.js` | `test/wrapper-fixtures.test.js`, `test/endpoints.test.js`, `test/client.test.js`, `test/errors.test.js` | Error response table is not specified in Crawleo docs. |
+| `/headful-browser` | `headful_browser` | `contracts/crawleo-endpoints.json` id `headful_browser` | `client.headfulBrowser` / `headfulBrowser(client, params)` | Wrapper API and covered capabilities table | `examples/offline-fake-fetch.js` | `test/wrapper-fixtures.test.js`, `test/endpoints.test.js`, `test/errors.test.js` | Documented by endpoint docs but absent from the local OpenAPI snapshot; error response table is not specified in Crawleo docs. |
+
+## Verification Surfaces
+
+- `npm run verify:contracts` verifies endpoint and MCP tool coverage in the contract inventory.
+- `npm test` verifies wrapper request construction, validation, response parsing, error normalization, live-test skip behavior, and secret redaction offline.
+- `npm run test:live` runs the optional live smoke test file; it skips unless both `CRAWLEO_API_KEY` and `CRAWLEO_ENABLE_LIVE_TESTS=1` are set.
+- `npm run verify:scaffold` verifies package files, public exports, README/SKILL references, live-test gate documentation, and this coverage checklist.
+
+## Live Verification Status
+
+Live Crawleo calls are intentionally not part of default verification. Optional live tests must require both `CRAWLEO_API_KEY` and `CRAWLEO_ENABLE_LIVE_TESTS=1` before making any request to Crawleo. Without both variables, `npm run test:live` exits 0 with the live test skipped.

package/contracts/crawleo-endpoint-evidence.md

@@ -0,0 +1,137 @@
+# Crawleo Endpoint Contract Evidence
+
+This file records the source evidence for S01 before the structured contract inventory is authored. Endpoint-specific Crawleo docs are treated as authoritative where the local OpenAPI snapshot is narrower.
+
+## Source Set
+
+- Crawleo docs index: `.gsd/research/crawleo-docs/llms.txt.txt` / `https://docs.crawleo.dev/llms.txt`
+- REST introduction: `.gsd/research/crawleo-docs/md/introduction.md` / `https://docs.crawleo.dev/api-reference/introduction.md`
+- Authentication: `.gsd/research/crawleo-docs/md/authentication.md` / `https://docs.crawleo.dev/authentication.md`
+- MCP overview: `.gsd/research/crawleo-docs/md/overview.md` / `https://docs.crawleo.dev/mcp/overview.md`
+- OpenAPI snapshot: `.gsd/research/crawleo-docs/openapi.json.json` / `https://docs.crawleo.dev/openapi.json`
+
+## Cross-Source Conflict Notes
+
+- The endpoint-specific docs and docs index list five REST capabilities: `/search`, `/google-search`, `/google-maps`, `/crawl`, and `/headful-browser`.
+- The local OpenAPI snapshot currently lists only `/search`, `/google-maps`, and `/crawl`.
+- S01 therefore keeps `/google-search` and `/headful-browser` because they are documented on endpoint-specific Crawleo docs pages and in the docs index.
+- Where fields are not explicitly documented, downstream contract files must use the phrase `not specified in Crawleo docs` rather than inventing behavior.
+
+## REST Endpoint Evidence
+
+### `/search` — Bing Search API
+
+- Source doc: `.gsd/research/crawleo-docs/md/search.md`
+- Source URL: `https://docs.crawleo.dev/api-reference/endpoint/search.md`
+- Endpoint evidence: `GET https://api.crawleo.dev/search`
+- Authentication evidence: required `x-api-key` header; docs also allow `Authorization: Bearer YOUR_API_KEY`.
+- Required query parameter: `query` string.
+- Documented optional parameters include:
+  - `max_pages` integer, default `1`; each page costs 10 credits.
+  - `setLang` string language code examples: `en`, `es`, `fr`, `de`.
+  - `cc` string country code examples: `US`, `GB`, `DE`.
+  - `geolocation` string; docs mention `random` for randomized geolocation.
+  - `device` string, default `desktop`; documented options: `desktop`, `mobile`, `tablet`.
+  - SERP toggles: `copilot_answer`, `questions_answers`, `related_queries`, `sidebar`, `direct_answer`; each default `true`.
+  - Page-content toggles: `raw_html`, `enhanced_html`, `page_text`, `markdown`; each default `false` in the endpoint doc.
+  - `auto_crawling` boolean, default `false`.
+- Example evidence: basic search request uses `https://api.crawleo.dev/search?query=machine%20learning&count=10` even though `count` is not listed in the visible parameter table; this must be marked as an ambiguity before implementation.
+- Response evidence fields include `query`, `pages_fetched`, `pages`, `total_results`, `search_results`, result `title`, `link`, `date`, `snippet`, `source`, `related_queries`, `page_content`, `enhanced_html`, `page_markdown`, and `credits`.
+- Error response table: not specified in Crawleo docs.
+- MCP mapping: `search_web` from MCP overview.
+
+### `/google-search` — Google Search API
+
+- Source doc: `.gsd/research/crawleo-docs/md/google-search.md`
+- Source URL: `https://docs.crawleo.dev/api-reference/endpoint/google-search.md`
+- Endpoint evidence: `GET https://api.crawleo.dev/google-search`
+- Cost evidence: 10 credits per request.
+- Authentication evidence: required `x-api-key` header; docs also allow `Authorization: Bearer YOUR_API_KEY`.
+- Required query parameter: `q` string.
+- Documented optional parameters include:
+  - `gl` string, default `us`; ISO 3166-1 alpha-2 examples include `us`, `gb`, `eg`, `de`, `fr`.
+  - `hl` string, default `en`; IETF language tag examples include `en`, `ar`, `fr`, `de`.
+  - `tbs` string; documented values include `qdr:h`, `qdr:d`, `qdr:w`, `qdr:m`, `qdr:y`.
+  - `page` integer, default `1`; 1-indexed.
+  - `num` integer, default `10`; documented range `1–100`.
+  - `type` string, default `search`; documented values: `search`, `news`, `images`, `places`, `shopping`.
+- Response evidence fields include `parameters`, `google_search_results`, result `title`, `link`, `snippet`, `position`, `knowledgeGraph`, `peopleAlsoAsk`, `relatedSearches`, and `answerBox`.
+- Error evidence: `400` missing `q`, `401` invalid/missing API key, `402` insufficient credits, `429` rate limit exceeded, `500` internal server error.
+- MCP mapping: endpoint doc states tool name `google_search`; MCP overview also lists `google_search`.
+
+### `/google-maps` — Google Maps API
+
+- Source doc: `.gsd/research/crawleo-docs/md/google-maps.md`
+- Source URL: `https://docs.crawleo.dev/api-reference/endpoint/google-maps.md`
+- Endpoint evidence: `GET https://api.crawleo.dev/google-maps`
+- Cost evidence: endpoint doc says 30 credits per request; MCP overview says `google_maps` costs 10 credits per request. Preserve this as a source conflict until resolved.
+- Authentication evidence: required `x-api-key` header; docs also allow `Authorization: Bearer YOUR_API_KEY`.
+- Required query parameter: `q` string; accepts business names, landmarks, addresses, keywords, and category + location queries.
+- Documented optional parameters include:
+  - `hl` string ISO 639-1 language code; examples include `en`, `ar`, `fr`, `de`.
+  - `ll` string location bias in format `@latitude,longitude,zoomz`; zoom range documented as `1z` to `21z`.
+  - `placeId` string Google Place ID for direct lookup.
+  - `cid` string Google numeric business/customer ID for direct business lookup.
+- Parameter combination evidence includes `q` only, `q + hl`, `q + ll`, `q + ll + hl`, `q + placeId`, `q + placeId + hl`, `q + cid`, and `q + cid + hl`.
+- Response evidence fields include `parameters`, `google_maps_results`, result `position`, `title`, `address`, `rating`, `ratingCount`, `phoneNumber`, `website`, `type`, `types`, `priceLevel`, `placeId`, `cid`, `latitude`, `longitude`, `openingHours`, `thumbnailUrl`, and `credits`.
+- Error evidence: `400` missing `q`, `401` invalid/missing API key, `403` inactive account or expired subscription, `429` credits exhausted or concurrent request limit reached, `500` internal server error.
+- MCP mapping: `google_maps` from MCP overview.
+
+### `/crawl` — Crawler API
+
+- Source doc: `.gsd/research/crawleo-docs/md/crawler.md`
+- Source URL: `https://docs.crawleo.dev/api-reference/endpoint/crawler.md`
+- Endpoint evidence: `GET https://api.crawleo.dev/crawl`
+- Authentication evidence: required `x-api-key` header; docs also allow `Authorization: Bearer YOUR_API_KEY`.
+- Required query parameter: `urls` string; accepts a single URL or comma-separated list.
+- Documented optional parameters include:
+  - `render_js` boolean, default `false`; `true` browser rendering costs 10 credits per URL, `false` HTTP request costs 1 credit per URL.
+  - `geolocation` string ISO 3166-1 alpha-2 country code.
+  - Output toggles: `raw_html` default `false`, `enhanced_html` default `true`, `page_text` default `false`, `markdown` default `true`.
+  - Screenshot toggles: `screenshot` default `false`, `screenshot_full_page` default `false`; screenshots are only available when `render_js=true`, and `screenshot=true` without JavaScript rendering is ignored.
+- Response evidence fields include `results`, per-result `url`, `status_code`, `raw_html`, `enhanced_html`, `markdown`, `page_text`, `screenshot`, `error`, plus top-level `credits` and `successful_pages`.
+- Error response table: not specified in Crawleo docs.
+- MCP mapping: `crawl_web` from MCP overview.
+
+### `/headful-browser` — Headful Browser API
+
+- Source doc: `.gsd/research/crawleo-docs/md/headful-browser.md`
+- Source URL: `https://docs.crawleo.dev/api-reference/endpoint/headful-browser.md`
+- Endpoint evidence: `GET https://api.crawleo.dev/headful-browser`
+- Cost evidence: 50 credits per URL; failed requests cost 0 credits.
+- Authentication evidence: required `x-api-key` header; docs also allow `Authorization: Bearer YOUR_API_KEY`.
+- Required query parameter: `urls` string; accepts one or more URLs as a single URL or comma-separated list.
+- Documented optional parameters include:
+  - `country` string, default `us`; supported examples include `us`, `gb`, `de`, `fr`, `jp`, `in`, `br`, `ca`, `au`, and more.
+  - `output_format` string, default `markdown`; documented values: `markdown`, `enhanced_html`, `raw_html`, `page_text`.
+  - `screenshot` boolean, default `false`; screenshot is returned as a URL.
+- Response evidence fields include `status`, `data`, per-item `url`, `markdown`, `raw_html`, `enhanced_html`, `page_text`, `screenshot`, `blocked`, `credits_used`, and `credits_remaining`.
+- Error response table: not specified in Crawleo docs.
+- MCP mapping: endpoint doc states tool name `headful_browser`; MCP overview also lists `headful_browser`.
+
+## MCP Tool Evidence
+
+- Source doc: `.gsd/research/crawleo-docs/md/overview.md`
+- Source URL: `https://docs.crawleo.dev/mcp/overview.md`
+- MCP endpoint: `https://api.crawleo.dev/mcp`
+- Documented tools:
+  - `search_web` — Bing-powered web search with auto-crawling; cost 10 credits per page of results.
+  - `google_search` — Google SERP data; cost 10 credits per request.
+  - `google_maps` — Google Maps places/business search; MCP overview says 10 credits per request, conflicting with endpoint doc's 30 credits per request.
+  - `crawl_web` — URL crawling/content extraction; cost 1 credit per URL for HTTP request and 10 credits per URL for browser rendering.
+  - `headful_browser` — premium headed browser crawling; cost 50 credits per URL.
+
+## OpenAPI Evidence
+
+- Source file: `.gsd/research/crawleo-docs/openapi.json.json`
+- Source URL: `https://docs.crawleo.dev/openapi.json`
+- Paths present in the local snapshot: `/search`, `/google-maps`, `/crawl`.
+- Paths absent from the local snapshot but present in endpoint docs and docs index: `/google-search`, `/headful-browser`.
+
+## Downstream Contract Rules
+
+- Use Crawleo-only naming and branding.
+- Use endpoint-specific docs over OpenAPI when OpenAPI omits an endpoint.
+- Preserve source conflicts, especially Google Maps cost discrepancy, instead of choosing silently.
+- Use `not specified in Crawleo docs` for missing error tables, undocumented defaults, unclear ranges, or example-only parameters not listed in parameter tables.
+- Do not include any live Crawleo calls in default verification.