docs: cover the new request options in the migration guide

[robertabbott]

Why

Merge this before #8. #11 landed before the release PR, so the 16 request options ship inside 3.0.0 rather than a later minor. MIGRATING.md was written when 3.0.0 was only the wire realignment, which leaves the migration guide describing a smaller release than the one about to publish — and leaves one line the release itself contradicts.

The contradiction, at MIGRATING.md:103:

Raising it needs max_rows, which this SDK does not expose yet.

3.0.0 exposes maxRows. This is the same class as the README line that said requesting a specific format "is not configurable yet" — true when written, false at publish, and pointed at exactly the reader least able to tell.

What changed

One file, +31/-2. A New options section covering only what a 2.x reader would otherwise get wrong; the README already carries the full tables and this does not restate them.

Item	Why a 2.x reader needs it
TakoCardSourceOptions → TakoDataSourceOptions	The alias still works, so nothing breaks. But data and web options are no longer interchangeable, so one object passed to both sources.data and sources.web stops type-checking against the new fields.
content_format now names two things	The response field renamed from format, and a new request option that chooses it — same concept, opposite direction. Shown side by side, since the guide already has a section about the response field under that name.
maxRows	Over-ceiling values are clamped, not rejected, and billing counts rows actually returned. A short export, a charge, no error.
quoteOnly	Free price check; returns no content, and the API ignores mode/contentFormat on a quote.
strict	Throws at takoSearch()/takoAnswer() without nodeIds; ids come from /v1/graph, which this SDK does not wrap.
sources.data.mode	Accepted and inert. Stated so nobody debugs why it does nothing.

Also softens the opening scope line, which promised type realignment only, and separates "changes that may require an edit" from "additive options that never do".

Verification

Docs only — no src/ or tests/ change, so no version bump. release-please folds this into the pending 3.0.0 release rather than cutting another.

• 84 tests, typecheck, and the conformance compile all clean (unchanged, as expected)
• Every claim checked against src/ and the vendored spec: the deprecated alias at src/types.ts:102, the construction-time assert in both tool factories, quoteOnly ignoring mode and contentFormat, and the two differing content_format defaults
• The ./README.md#search-and-answer-options anchor resolves against an actual heading
• grep confirms no "does not expose / not configurable / not surfaced yet" claim survives anywhere in MIGRATING.md, README.md, or src/

Dropped one claim during review of my own draft: an earlier version opened with "2.x could reach 6 of the API's 22 request options." That number is not defensible — it depends on whether you count container properties like sources and output_settings alongside their nested leaves. Replaced with the figure the contract suite actually asserts: 16 newly reachable, and every property of every request schema now covered.

What this does not do

Does not document the /v1/graph endpoints nodeIds depends on — this SDK does not wrap them, and the guide says so rather than implying otherwise.

🤖 Generated with Claude Code

[robertabbott]

Validated the whole option surface against the live API (staging, employee token) before this ships. 20 checks, everything documented here now confirmed against behavior rather than the spec document alone.

The claim I could not previously verify is now verified. maxRows: 999999 returns HTTP 200 with the cost clamped to the 2,000-row price, not a 400 — so the clamp-and-bill warning in this guide and the README is correct.

Check	Result
{query} alone, no effort/country_code/locale	200, same response shape and same 5 web results as sending them explicitly — the defaults removal is behavior-neutral against the live API, not just the spec
All 10 new search options	200, none rejected
includeDomains	filters — 8/8 results from the requested host, and multi-domain works
excludeDomains	filters — named host absent from results
contentFormat: json_records	honored, records populated (20 rows)
contentFormat: json_compact	honored, dataset present
quoteOnly	200, url and payload null, export_pricing present, free_rows: 20, ceiling: 2000
maxRows over ceiling	200, clamped — confirms the doc

One finding fed back into the docs (407a99f). A quote returns a non-zero cost while billing nothing, and it scales with maxRows — 20 rows quoted 0.001, 100 0.081, 500 0.481, 2000 1.981. The old wording "the request is free and the payload is null" was true but invited someone to see cost: 0.481 and think they had been charged. Both copies now say cost is the quoted price.

Two things worth recording that are not defects here:

• sources.data.count: 0 is accepted with a 200 even though the schema declares minimum: 1. Consistent with this SDK deliberately not mirroring bounds; noting it as an API-side observation.
• Results are from staging, so treat the filtering and pricing figures as indicative rather than a prod guarantee. Acceptance, defaulting, and clamping are contract-level and should not differ.

No probe code is committed — it read the host and token from the environment and was deleted. @claude-address