doc: add portable agentic instructions

.claude/.gitignore

@@ -0,0 +1,5 @@
+plans/
+skills/
+commands/
+agents/
+hooks/

.claude/CLAUDE.md

@@ -0,0 +1,85 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Go types modeling the [Swagger 2.0 / OpenAPI 2.0](https://swagger.io/specification/v2/)
+specification. Every object in the spec --- `Swagger`, `Info`, `PathItem`, `Operation`,
+`Parameter`, `Schema`, `Response`, `Header`, `SecurityScheme`, etc. --- has a corresponding
+Go struct with JSON serialization (`encoding/json`) that round-trips through the spec's
+JSON representation.
+
+This package is the **foundational data model** for the
+[go-swagger](https://github.com/go-swagger/go-swagger) ecosystem. Higher-level packages
+(`analysis`, `loads`, `validate`, `runtime`) consume these types to load, analyze, validate,
+and serve Swagger specifications. Because it sits at the bottom of the dependency graph,
+changes here ripple through the entire ecosystem.
+
+Key capabilities beyond plain structs:
+
+- **`$ref` resolution** --- the `Ref` type wraps JSON Reference pointers; the `expander`
+  resolves `$ref` nodes (local, remote, circular) into fully expanded specs.
+- **Schema composition** --- `Schema` supports `allOf`, `additionalProperties`,
+  `additionalItems`, and JSON Schema validations (`minimum`, `pattern`, `enum`, etc.).
+- **URL normalization** --- cross-platform path/URL normalization for `$ref` targets.
+- **Embedded spec** --- a copy of the Swagger 2.0 JSON Schema is embedded via `go:embed`
+  for offline use.
+
+See [docs/MAINTAINERS.md](../docs/MAINTAINERS.md) for CI/CD, release process, and repo structure details.
+
+### Package layout (single package)
+
+| File | Contents |
+|------|----------|
+| `swagger.go` | Root `Swagger` type (top-level spec object) |
+| `info.go` | `Info`, `ContactInfo`, `LicenseInfo` |
+| `paths.go` | `Paths` (map of path patterns to `PathItem`) |
+| `path_item.go` | `PathItem` (GET/PUT/POST/DELETE/... operations per path) |
+| `operation.go` | `Operation` (single API operation) |
+| `parameter.go` | `Parameter` (query, header, path, body, formData) |
+| `header.go` | `Header` |
+| `response.go`, `responses.go` | `Response`, `Responses` |
+| `schema.go` | `Schema` (JSON Schema subset used by Swagger) |
+| `security_scheme.go` | `SecurityScheme` |
+| `items.go` | `Items` (non-body parameter schema) |
+| `ref.go` | `Ref` type, JSON Reference (`$ref`) handling |
+| `expander.go` | `$ref` expansion / resolution engine |
+| `normalizer.go` | URL/path normalization (platform-specific variants) |
+| `cache.go` | Resolution cache for expanded specs |
+| `validations.go` | Common validation properties shared across types |
+| `properties.go` | `SchemaProperties` ordered map |
+| `embed.go` | Embedded Swagger 2.0 JSON Schema (`go:embed`) |
+| `spec.go` | `MustLoadSwagger20Schema()` loader |
+| `external_docs.go` | `ExternalDocumentation` |
+| `tag.go` | `Tag` |
+| `xml_object.go` | `XMLObject` |
+| `debug.go` | Debug logging helpers |
+
+### Key API
+
+- `Swagger` --- root specification object; deserialize with `json.Unmarshal`
+- `Schema` --- JSON Schema with Swagger extensions; supports `allOf`, `$ref`, validations
+- `Ref` / `MustCreateRef(uri)` --- JSON Reference wrapper
+- `ExpandSpec(spec, opts)` --- resolve all `$ref` nodes in a specification
+- `ExpandSchema(schema, root, cache)` --- resolve `$ref` nodes in a single schema
+- `ResolveRef(root, ref)` / `ResolveParameter` / `ResolveResponse` --- targeted resolution
+
+### Dependencies
+
+- `github.com/go-openapi/jsonpointer` --- JSON Pointer (RFC 6901) navigation
+- `github.com/go-openapi/jsonreference` --- JSON Reference parsing
+- `github.com/go-openapi/swag` --- JSON/YAML utilities, name mangling
+- `github.com/go-openapi/testify/v2` --- test-only assertions (zero-dep testify fork)
+
+### Notable historical design decisions
+
+- **Mixin of spec types and `$ref`** --- many types embed both their data fields and a `Ref`
+  field. When `$ref` is present, the data fields are ignored per the Swagger specification.
+  This is modeled by custom `MarshalJSON`/`UnmarshalJSON` on each type.
+- **`VendorExtensible`** --- most types embed `VendorExtensible` to capture `x-` extension
+  fields as `map[string]any`.
+- **`SchemaProperties` as ordered slice** --- schema properties are stored as a slice of
+  key-value pairs (not a map) to preserve declaration order during round-trip serialization.
+- **Platform-specific normalization** --- Windows path handling differs from Unix; separate
+  `normalizer_windows.go` / `normalizer_nonwindows.go` files handle this.

.claude/rules/contributions.md

@@ -0,0 +1,52 @@
+---
+paths:
+  - "**/*"
+---
+
+# Contribution rules (go-openapi)
+
+Read `.github/CONTRIBUTING.md` before opening a pull request.
+
+## Commit hygiene
+
+- Every commit **must** be DCO signed-off (`git commit -s`) with a real email address.
+  PGP-signed commits are appreciated but not required.
+- Agents may be listed as co-authors (`Co-Authored-By:`) but the commit **author must be the human sponsor**.
+  We do not accept commits solely authored by bots or agents.
+- Squash commits into logical units of work before requesting review (`git rebase -i`).
+
+## Linting
+
+Before pushing, verify your changes pass linting against the base branch:
+
+```sh
+golangci-lint run --new-from-rev master
+```
+
+Install the latest version if you don't have it:
+
+```sh
+go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest
+```
+
+## Problem statement
+
+- Clearly describe the problem the PR solves, or reference an existing issue.
+- PR descriptions must not be vague ("fix bug", "improve code") — explain *what* was wrong and *why* the change is correct.
+
+## Tests are mandatory
+
+- Every bug fix or feature **must** include tests that demonstrate the problem and verify the fix.
+- The only exceptions are documentation changes and typo fixes.
+- Aim for at least 80% coverage of your patch.
+- Run the full test suite before submitting:
+
+For mono-repos:
+```sh
+go test work ./...
+```
+
+For single module repos:
+```sh
+go test ./...
+```