用途：当 OpenAPI 规范存在 lint 或验证错误，但源规范无法直接修改时，使用 overlay 文件进行修复，而非改动源规范。
适用场景：存在 lint 错误但不能编辑源规范；需要补充缺失的描述、标签或操作名称；用户提出“fix with overlay”“can't edit spec”“add missing descriptions”等需求。
输入：OpenAPI 规范（必需，含验证错误的规范）；lint 输出（有帮助，指出待修复错误）。输出：overlay 文件，记录对验证问题的修复。
适合用 overlay 的修复类型：操作名不佳时使用 x-speakeasy-name-override；缺失描述时补充 summary 或 description；缺失标签时添加 tags 数组；操作分组使用 x-speakeasy-group；重试配置使用 x-speakeasy-retries。
不适合用 overlay 的问题：无效 JSON/YAML 属于源语法错误；缺失必需字段属于 schema 不完整；损坏的 $ref；数据类型错误属于 API 设计问题。这些结构性问题必须直接修改源规范，不应尝试用 overlay 绕过，也不应忽略这类错误。
基本流程：先用 speakeasy suggest operation-ids -s openapi.yaml -o fixes.yaml 生成建议；再编辑 .speakeasy/workflow.yaml 将 overlay 纳入工作流；最后执行 speakeasy run --output console 重新生成。
排查：overlay 未应用，通常是未加入 workflow.yaml，需把 overlay 加到 sources.overlays；target not found，可能是 JSONPath 错误，需核对路径是否与规范完全匹配；错误仍然存在，说明该问题不适合用 overlay 修复，需检查是否应改源规范。
相关技能：validate-openapi-spec、create-openapi-overlay、get-ai-suggestions、diagnose-generation-failure。