doc: added instructions for claude and copilot

Signed-off-by: Frederic BIDON <fredbi@yahoo.com>

Author: fredbi

.claude/CLAUDE.md

@@ -4,41 +4,45 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-Go implementation of [JSON Pointer (RFC 6901)](https://datatracker.ietf.org/doc/html/rfc6901) for navigating
-and mutating JSON documents represented as Go values. Unlike most implementations, it works not only with
-`map[string]any` and slices, but also with Go structs (resolved via `json` struct tags and reflection).
+Go library for validating OpenAPI v2 (Swagger) specifications and JSON Schema draft 4 data.
+It is part of the [go-openapi](https://github.com/go-openapi) ecosystem and used by [go-swagger](https://github.com/go-swagger/go-swagger).
+
+The library provides two main capabilities:
+1. **Spec validation** — validates a Swagger 2.0 spec document against the JSON meta-schema, plus extra semantic rules (path uniqueness, parameter consistency, $ref resolution, etc.)
+2. **Schema validation** — validates arbitrary data against a JSON Schema draft 4 schema (tested against the official JSON-Schema-Test-Suite)
+
+API is stable. This is legacy/maintenance code — deep refactoring is not worthwhile;
+a ground-up replacement is the long-term plan.
 
 See [docs/MAINTAINERS.md](../docs/MAINTAINERS.md) for CI/CD, release process, and repo structure details.
 
-### Package layout (single package)
+### Package layout
 
-| File | Contents |
-|------|----------|
-| `pointer.go` | Core types (`Pointer`, `JSONPointable`, `JSONSetable`), `New`, `Get`, `Set`, `Offset`, `Escape`/`Unescape` |
-| `errors.go` | Sentinel errors: `ErrPointer`, `ErrInvalidStart`, `ErrUnsupportedValueType` |
+| Package | Contents |
+|---------|----------|
+| `validate` (root) | Spec validator (`SpecValidator`), schema validator (`SchemaValidator`), `AgainstSchema()`, individual type/format/object/slice/string/number validators, result handling, pools |
+| `post` | Post-validation transforms: `ApplyDefaults` (fills in schema defaults) and `Prune` (removes additional properties) |
 
 ### Key API
 
-- `New(string) (Pointer, error)` — parse a JSON pointer string (e.g. `"/foo/0/bar"`)
-- `Pointer.Get(document any) (any, reflect.Kind, error)` — retrieve a value
-- `Pointer.Set(document, value any) (any, error)` — set a value (document must be pointer/map/slice)
-- `Pointer.Offset(jsonString string) (int64, error)` — byte offset of token in raw JSON
-- `GetForToken` / `SetForToken` — single-level convenience helpers
-- `Escape` / `Unescape` — RFC 6901 token escaping (`~0` ↔ `~`, `~1` ↔ `/`)
-
-Custom types can implement `JSONPointable` (for Get) or `JSONSetable` (for Set) to bypass reflection.
+- `Spec(doc, formats) error` — high-level spec validation
+- `NewSpecValidator(schema, formats) *SpecValidator` — configurable spec validator
+- `AgainstSchema(schema, data, formats, ...Option) error` — validate data against a JSON schema
+- `NewSchemaValidator(schema, root, path, formats, ...Option) *SchemaValidator` — configurable schema validator
+- `post.ApplyDefaults(result)` — apply default values from validation result
+- `post.Prune(result)` — remove undeclared properties from validation result
 
 ### Dependencies
 
-- `github.com/go-openapi/swag/jsonname` — struct tag → JSON field name resolution
-- `github.com/go-openapi/testify/v2` — test-only assertions
-
-### Notable historical design decisions
+Key runtime dependencies (see `go.mod` for full list):
+- `github.com/go-openapi/spec` — Swagger 2.0 spec model
+- `github.com/go-openapi/analysis` — spec analysis and flattening
+- `github.com/go-openapi/loads` — spec loading (used in tests/examples)
+- `github.com/go-openapi/errors` — structured validation errors
+- `github.com/go-openapi/strfmt` — format registry (date-time, uuid, email, etc.)
+- `github.com/go-openapi/testify/v2` — test-only assertions (zero-dep testify fork)
 
-See also .claude/plans/ROADMAP.md.
+### Architecture notes
 
-- Struct fields **must** have a `json` tag to be reachable; untagged fields are ignored
-  (differs from `encoding/json` which defaults to the Go field name).
-- Anonymous embedded struct fields are traversed only if tagged.
-- The RFC 6901 `"-"` array suffix (append) is **not** implemented.
+The validator chain is built from `valueValidator` implementations (type, format, string, number, slice, object, common, schemaProps), assembled by `SchemaValidator`. Validators and results are pooled for performance (`pools.go`). The codebase has known complexity issues (many `//nolint:gocognit` deferrals) stemming from the original design.
 

.github/copilot-instructions.md

@@ -2,19 +2,27 @@
 
 ## Project Overview
 
-Go implementation of a OpenAPI v2 (swagger) validator and JSON Schema draft 4 validator
+Go library for validating OpenAPI v2 (Swagger) specifications and JSON Schema draft 4 data.
+Part of the [go-openapi](https://github.com/go-openapi) ecosystem. API is stable; maintenance-only.
 
-## Package Layout (single package)
+## Package Layout
 
-| File | Contents |
-|------|----------|
+| Package | Contents |
+|---------|----------|
+| `validate` (root) | Spec validator, schema validator, type/format/object/slice/string/number validators, result handling, pools |
+| `post` | Post-validation transforms: `ApplyDefaults` and `Prune` |
 
 ## Key API
 
-## Design Decisions
+- `Spec(doc, formats) error` — high-level spec validation
+- `AgainstSchema(schema, data, formats, ...Option) error` — validate data against a JSON schema
+- `NewSchemaValidator(schema, root, path, formats, ...Option) *SchemaValidator`
+- `post.ApplyDefaults(result)` / `post.Prune(result)`
 
 ## Dependencies
 
+- `github.com/go-openapi/spec`, `analysis`, `loads`, `errors`, `strfmt`
+
 ## Conventions
 
 - All `.go` files must have SPDX license headers (Apache-2.0).