doc: add portable agentic instructions

.claude/.gitignore

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

.claude/CLAUDE.md

@@ -0,0 +1,52 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Go implementation of [JSON Reference](https://datatracker.ietf.org/doc/html/draft-pbryan-zyp-json-ref-03)
+(RFC 3986-based URI references with JSON Pointer fragments). JSON References are used
+extensively in OpenAPI and JSON Schema specifications to express `$ref` links between
+documents and within a single document.
+
+The `Ref` type parses a reference string into its URL and JSON Pointer components, classifies
+it (full URL, path-only, fragment-only, file scheme), and supports inheritance (resolving a
+child reference against a parent).
+
+See [docs/MAINTAINERS.md](../docs/MAINTAINERS.md) for CI/CD, release process, and repo structure details.
+
+### Package layout (single package)
+
+| File | Contents |
+|------|----------|
+| `reference.go` | `Ref` type, constructors (`New`, `MustCreateRef`), accessors (`GetURL`, `GetPointer`, `String`), classification (`IsRoot`, `IsCanonical`), and `Inherits` for parent-child resolution |
+| `internal/normalize_url.go` | URL normalization (lowercase scheme/host, remove default ports, deduplicate slashes) — replaces the deprecated `purell` library |
+
+### Key API
+
+- `Ref` — the core type representing a parsed JSON Reference
+- `New(string) (Ref, error)` — parse a JSON Reference string
+- `MustCreateRef(string) Ref` — parse or panic
+- `(*Ref).GetURL() *url.URL` — the underlying URL
+- `(*Ref).GetPointer() *jsonpointer.Pointer` — the JSON Pointer fragment
+- `(*Ref).Inherits(child Ref) (*Ref, error)` — resolve a child reference against this parent
+- `(*Ref).IsRoot() bool` — true if this is a root document reference
+- `(*Ref).IsCanonical() bool` — true if the reference starts with `http(s)://` or `file://`
+
+### Dependencies
+
+- `github.com/go-openapi/jsonpointer` — JSON Pointer (RFC 6901) implementation
+- `github.com/go-openapi/testify/v2` — test-only assertions (zero-dep testify fork)
+
+### Notable design decisions
+
+- **Replaced `purell` with internal normalization** — the `internal/normalize_url.go` file
+  replaces the unmaintained `purell` library. It performs only the safe normalizations that
+  were previously used: lowercase scheme/host, remove default HTTP(S) ports, and deduplicate
+  path slashes.
+- **Classification flags on `Ref`** — rather than re-parsing on each query, the `parse` method
+  sets boolean flags (`HasFullURL`, `HasURLPathOnly`, `HasFragmentOnly`, `HasFileScheme`,
+  `HasFullFilePath`) once at construction time.
+- **JSON Pointer errors are silently ignored** — if the URL fragment is not a valid JSON Pointer,
+  the pointer is left as zero-value. This allows the type to represent any URI reference, not
+  just those with valid JSON Pointer fragments.

.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 ./...
+```