docs: validator, converter and joiner docs do not describe the v1.59.0 behavior changes

[erraggy]

v1.59.0 changed what the validator accepts and what the joiner merges. The corrections that were wrong landed with the release (stale field lists, broken golangci-lint install instructions); this is the documentation that needs adding rather than fixing.

validator/doc.go

Two changes make previously-passing documents fail, and neither is documented:

• A document declaring 3.0.x or 3.1.x that uses any OAS 3.2 fixed field now gets an error, not a warning (validator/oas32_gate.go).
• Schemas in responses, parameters, headers, encoding headers and callbacks are validated for the first time. Per validator/schema_traversal.go's own header: "Every schema in a response, a parameter or a header was therefore never validated at all."

Wants a # Version-Specific Fields section, and a sentence in Features that schema validation reaches every schema position.

Also undocumented from #412's validator work: Example dataValue/serializedValue exclusivity, in: "querystring" conflict rules, XML nodeType, Discriminator defaultMapping.

validator/deep_dive.md

"Component schemas undergo structural validation" was accurate before #426 and now understates the scope. Needs a scope sentence plus a subsection for the 3.2 field gate, parallel to the existing "Path Parameter Consistency" prose.

Note this file is the source for the generated docs/packages/validator.md — edit here, then rebuild.

converter/doc.go

The "cannot convert to OAS 2.0" paragraph does not mention 3.x→3.x loss at all. converter.go now runs detectOAS32Features whenever the target is below 3.2, so a 3.2 → 3.0.3 conversion — which the doc frames as trivially safe — emits a new warning class:

'<field>' is OAS 3.2+ only and has no equivalent in OAS <target>

with remediation noting the field is preserved, leaving output that is no longer a valid document for that target.

joiner/doc.go and joiner/deep_dive.md

The seven-field documentation set was corrected in the release. What is still missing is the larger #416 change: deep comparison previously read 38 of parser.Schema's 65 fields, so schemas differing only in nullability, in which property discriminates a union, or in OAS 2.0 array serialization were reported equivalent and merged. StrategyDeduplicateEquivalent and SemanticDeduplication now keep those apart.

converter/deep_dive.md

"Supported conversions" omits 3.2 entirely while a later section recommends 3.2.0 as a target. "What Cannot Convert" and "Downgrading to OAS 2.0" need the 3.2 fixed fields; there is no 3.2→3.0/3.1 counterpart to the existing "OAS 3.1 → OAS 3.0" table.

Smaller

• CLAUDE.md Key Patterns: internal/driftguard appears in no .md file repo-wide, so an agent adding a parser field discovers it by CI failure. A field must be handled in the hand-built MarshalJSON path, the structural hasher, the type's equality function, and the joiner's schema comparison.
• docs/cli-reference.md: "OAS 3.x | OAS 3.y | Version updates supported" understates a 3.2→3.0 downgrade.
• docs/developer-guide.md: the 3.2 example shows only Self, Query, AdditionalOperations; line ~782 uses joiner.JoinerConfig{...} direct struct instantiation, which joiner/doc.go explicitly calls out as incorrect usage (pre-existing).
• .claude/docs/make-commands.md: lists make lint but not make lint-install.
• .claude/docs/testing-requirements.md: make test gained -coverpkg=./... in fix(ci): pin golangci-lint to one version, and fail corpus downloads loudly #415, which changes coverage attribution across packages.