[th0rntwig]

🔴 Review tier: HIGH — human review required

• Size: 42 files, almost all of them recipe renames paired with their regenerated markdown
• Money: the recipes state credit costs and plan caps that only take effect once stories-service and api fix/news-search-defaults are deployed; do not merge before that deploy

What

Brings the cookbook in line with how news search behaves after the news-search-defaults change, and renames every recipe so people and AI agents can tell from the title which one fits their task.

Aligned with news search

• The search window alone decides whether the archive is searched. A search whose window starts more than 48 hours ago costs 5 credits, and so does each of its pages. Searches with strategy="news knowledge" or only an end_timestamp cost 5 credits too.
• historical is described as deprecated with no effect, and the examples leave it out.
• Plan caps on n_articles: Pay as you go, Pro and Spelunker accept up to 10, the default, and get a 400 above it. Analyst and Enterprise are reduced to 30. The examples use 10.
• Also corrected: the 160-day window, pagination limits, result order, plan gates, and no scopes next to an API key.

Recipe names and framing

• Titles are imperative task names in the docs' vocabulary, and each filename is its title as a slug (for example 01_search_live_news, 09_monitor_a_company, 12_run_deep_research, 14_prompt_deep_research).
• Every recipe opens with a Use this when line that frames its use case. cookbook/build.py copies that line into markdown/index.md next to each title.
• DeepNews (12–14) is framed as a research agent. It plans its own searches and returns a cited answer. It also brings in related context the question did not ask for. Recipe 14 covers directing the agent: which tools to use and how, what to focus on, and how to format the output.
• The endpoint table in 00 links every recipe from the row of the endpoint it uses.
• cookbook/README.md lists every recipe with its Use this when line, the calls it makes and what it covers. It also describes how to name a new recipe.

Verification

• python cookbook/build.py regenerates cookbook/markdown/; the committed markdown matches.
• Every cross-link in the recipes, the markdown and the README resolves.
• pytest: 184 passed.
• The cookbook is not in the wheel (packages = ["asknews_sdk"]), and docs: commits do not trigger a version bump.

Links

• Nothing on main or the frontend dev branch links to the old recipe filenames. The rewritten docs site (frontend docs/api-docs-rewrite) links to the new names, so it should ship after this PR.

🤖 Generated with Claude Code