## TL;DR
Read the RTD build log for the validation detail, then fix .readthedocs.yaml: correct the version field, the build jobs, and the python/sphinx requirements. Validate the file before pushing.

## The exact error
```text
Invalid .readthedocs.yaml
```

## Steps
1. **Read the build log**
   Open the failed RTD build and copy the config validation detail; it names the offending key and the expected shape.
   Success check: You know the exact key and what the validator expected.
2. **Fix the schema**
   Set version: 2 at the top. Put build commands under build.jobs, the OS and tools under build.os and build.tools, and dependencies under python.install.
   Success check: The file matches the v2 schema documented by Read the Docs.
3. **Check requirements wiring**
   Make sure python.install.requirements points at a real file and that sphinx and the theme are pinned in it. A missing requirements file fails later with a confusing pip error.
   Success check: The requirements file exists and installs cleanly in a fresh environment.
4. **Push and watch the build**
   Commit the fixed config and trigger a new RTD build; confirm it passes the validation step.
   Success check: The RTD build passes config validation and proceeds to the install step.

## When to use
- Use when a Read the Docs build dies on .readthedocs.yaml validation.
- Use when migrating a project from the old v1 config format to v2.

## When not to use
- Not for pip install failures after validation passes (dependency problem, not config).
- Not for builds that pass but render wrong (content or theme problem).

## Why it happens
Read the Docs validates .readthedocs.yaml against a strict schema before running any build step. The v1 to v2 migration renamed and restructured most keys, so configs copied from old tutorials fail validation immediately.

## Edge cases
The validator runs server-side, so a file that parses as YAML locally can still be invalid; always read the RTD build log rather than guessing. build.jobs lets you run custom commands, but each job step that exits nonzero fails the whole build.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_6m2PPUrKsGBC6ig0obSLtw