docs: carry generated-file ownership guidance to next (#4196)

Carry the reviewed generated-file ownership guidance from merged
#4193 into `next`, so
contributors follow the simplified generation model before its next
regeneration.

All four documents exactly match main commit
`1b37b9a85e857a7ada4db661bf867bf680290ccf`. They replace the retired
budget instructions with the rule to change generator inputs/compiler,
regenerate owned files, and keep handwritten behavior in separate
extensions. Ordinary review enforces ownership; no replacement checker
is introduced.

This is the handwritten-documentation prerequisite only. Generated
tools, inventory, generation metadata, runtime, dependencies, workflows,
and release behavior are unchanged; canonical next regeneration will
remove the retired generated tools separately.

Validation: basic review, exact byte comparison of all four documents
against the merged main commit, four-file scope assertion, and `git diff
--check` pass. No runtime tests were rerun for this documentation-only
change. SDK CODEOWNER review and normal next CI are required.

Author: jbeckwith-oai

AGENTS.md

@@ -7,15 +7,21 @@ changing generated files. Handwritten policy, automation, tests, and examples
 should remain small and should not alter exported SDK APIs unless the change
 explicitly requires it.
 
-## Custom-code budget
-
-Follow [the custom-code guidance](scripts/castiron/CUSTOM_CODE.md). Budget changes
-belong in a separate PR containing only `.castiron-ratchet.json`, with an explicit justification
-in the PR description. Increases require a **human approving review** before merging.
-Agents may investigate and draft proposals, but must not approve budget increases
-(including through a human's credentials) or bypass the gate. Do not weaken
-counting, broaden exclusions, or alter generation metadata to make a change pass.
-The checker and effective budget come from main, not the PR. Keep default CODEOWNERS.
+## Generated-file ownership
+
+Never hand-edit generated SDK files, including generated tests, documentation,
+workflows, or the generated-file inventory. Change the authoritative API schema,
+configuration, or compiler, then regenerate. Put SDK-specific behavior in
+separately owned handwritten helpers and extension points.
+
+Regeneration replaces generator-owned files and deletes retired generated paths.
+Handwritten edits to generated files are overwritten; they are never replayed or
+merged into new output. Preserve separately owned handwritten files and resolve
+ownership collisions explicitly. Follow this AGENTS.md rule and review generated output and inventory changes
+together. Generated-file ownership currently relies on contributor guidance and
+code review; there is no dedicated generated-file edit check or required gate.
+Fix violations in the inputs/compiler and regenerate; never update inventory
+hashes to accept a handwritten patch.
 
 ## Security requirements for coding agents
 

CONTRIBUTING.md

@@ -96,26 +96,25 @@ and [Dependabot's cooldown policy](https://docs.github.com/en/code-security/refe
 
 ## Modifying/Adding code
 
-Most of the SDK is generated code. Modifications to code will be persisted between generations, but may
-result in merge conflicts between manual patches and changes from the generator. The generator will never
+Most of the SDK is generated code. Never edit generated files by hand; change
+the authoritative generation inputs or compiler and regenerate instead. The generator will never
 modify the contents of the `src/openai/lib/` and `examples/` directories.
 
-## Custom-code budget
-
-The custom-code budget counts additions plus deletions in the remaining patch
-against verified generated output. `.castiron-ratchet.json` defines this repository's
-ceiling. CI uses the checker and budget on main, not the PR's proposed versions.
-
-Budget changes must be in a separate PR modifying **only `.castiron-ratchet.json`**.
-Justify the current usage, proposed ceiling, and why fixing generation is not
-appropriate in the PR description. Increases require a **human approving review**
-and must merge before an SDK change relies on them. Agents may draft proposals,
-but must not approve increases or bypass the gate. Keep default CODEOWNERS.
-Lower the ceiling after cleanup while retaining headroom; decreases must still
-fit the measured usage.
-
-See [custom-code technical details](scripts/castiron/CUSTOM_CODE.md) for accounting,
-local checks, trusted CI, and activation instructions.
+## Generated-file ownership
+
+Do not edit generated SDK files by hand. Fix the API schema, generation
+configuration, or compiler and regenerate instead. Put SDK-specific behavior in
+separately owned handwritten helpers and extension points.
+
+Regeneration replaces generated files and removes retired generated paths.
+Handwritten edits to generated output are overwritten, not carried forward.
+Separately owned handwritten files are preserved. Resolve ownership conflicts
+explicitly before regeneration. Follow the ownership rules in `AGENTS.md`
+and review generated output and inventory changes together. Generated-file
+ownership currently relies on contributor guidance and code review, without a
+dedicated generated-file edit check or required gate. Fix violations in the
+generation inputs/compiler and regenerate; do not edit inventory hashes to
+accept a handwritten patch.
 
 ## Security requirements for contributions