ingesting-spec

# Spec Ingestion ## Overview This skill describes how to ingest the latest OpenAI TypeSpec specification (from the upstream [`microsoft/openai-openapi-pr`](https://github.com/microsoft/openai-openapi-pr) repository) into the `openai-dotnet` SDK, area by area. The process involves: 1. Copying updated base specs from upstream 2. Reporting any compile errors in the base TSP 3. Fixing compile errors in the client TSP layer 4. Preserving custom C# code (renames, stubs) 5. Running code generation 6. Verifying the output ## Skill Documents This skill is split across multiple files for easier navigation: | Document | Description | |----------|-------------| | [steps.md](steps.md) | **Step-by-step process** — the full 9-step workflow from copying spec to post-generation verification | | [file-locations.md](file-locations.md) | **Key file locations** — quick reference for all upstream and local paths, area mappings | | [patterns-and-gotchas.md](patterns-and-gotchas.md) | **Common patterns & gotchas** — lessons learned, pitfalls, and conventions to follow | | [checklist.md](checklist.md) | **Checklist** — a task-by-task checklist for tracking progress during an ingestion | | [references.md](references.md) | **Reference PRs** — detailed notes on past ingestion PRs with lessons learned | ## Quick Start 1. Review [references.md](references.md) for examples of past ingestions in your area 2. Read [file-locations.md](file-locations.md) to understand the repo layout 3. Follow [steps.md](steps.md) for the full ingestion workflow 4. Use [checklist.md](checklist.md) to track your progress 5. Consult [patterns-and-gotchas.md](patterns-and-gotchas.md) when you hit issues ## Available Areas Areas that can be ingested independently: `administration` · `assistants` · `audio` · `batch` · `chat` · `containers` · `conversations` · `embeddings` · `evals` · `files` · `fine-tuning` · `graders` · `images` · `models` · `moderations` · `realtime` · `responses` · `runs` · `threads` · `vector-stores` · `videos` ## Key Rules 1. **Always add `@@clientLocation`** for every operation in the client TSP (the latest spec no longer uses `interface` blocks) 2. **Update `[CodeGenType]` stubs** in `src/Custom/{Area}/Internal/GeneratorStubs.cs` for any renamed types 3. **Defer complex features** — suggest them as follow-up items rather than implementing in the same ingestion 4. **Run `./scripts/Invoke-CodeGen.ps1`** to generate code (warnings are OK. Errors are not), then `dotnet build` to verify (Should be no warnings or errors) 5. **Work locally only** — do NOT create PRs or file issues. Instead, suggest a list of issues that may need to be filed upstream