doc: added READMEs per module, updated agentic instructions (#439)

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

Author: fredbi

.claude/CLAUDE.md

@@ -12,22 +12,23 @@ See [docs/MAINTAINERS.md](../docs/MAINTAINERS.md) for CI/CD, release process, an
 
 ### Modules and Package layout
 
-This is a mono-repo with a `go.work` workspace containing two modules:
+This is a mono-repo with a `go.work` workspace containing three modules:
 
 | Module | Purpose |
 |--------|---------|
 | `.` (root) | Core runtime library |
-| `client-middleware/opentracing` | Optional OpenTracing middleware for client transport |
+| `server-middleware` | Standalone, dependency-free server middleware: `mediatype`, `negotiate`, `negotiate/header`, `docui`. No transitive dependency on `go-openapi/spec`, `loads`, or `validate`. |
+| `client-middleware/opentracing` | Optional OpenTracing middleware for client transport (compatibility module; new code should use the OpenTelemetry support built into `client.Runtime`). |
 
 Packages in the root module:
 
 | Package | Contents |
 |---------|----------|
 | `runtime` (root) | Core interfaces (`Consumer`, `Producer`, `Authenticator`, `Authorizer`, `OperationHandler`), content-type handlers (JSON, XML, CSV, text, bytestream), HTTP request/response helpers |
 | `client` | HTTP client transport: `Runtime` with TLS, timeouts, proxy, keepalive, OpenTelemetry tracing |
-| `middleware` | Server-side request lifecycle: routing, content negotiation, parameter binding, validation, security, Swagger UI / RapiDoc serving |
+| `middleware` | Server-side request lifecycle: routing, parameter binding, validation, security, operation execution. Doc-UI and negotiation primitives have moved to `server-middleware/*`; the legacy entry points (`Spec`, `SwaggerUI`, `RapiDoc`, `Redoc`, `NegotiateContentType`, …) remain as deprecated shims in `seam.go`. |
 | `middleware/denco` | Internal path-pattern router |
-| `middleware/header` | HTTP header parsing utilities |
+| `middleware/header` | Deprecated shim — re-exports `server-middleware/negotiate/header` |
 | `middleware/untyped` | Untyped (reflection-based) API request/response handling |
 | `security` | Auth scheme implementations: Basic, API Key, Bearer/OAuth2 (with `*Ctx` context-aware variants) |
 | `logger` | `Logger` interface with `Printf`/`Debugf`; debug enabled via `SWAGGER_DEBUG` or `DEBUG` env vars |
@@ -59,7 +60,12 @@ Server middleware (`middleware` package):
 
 - `Context` — request lifecycle manager (routes, binds, validates, authenticates, executes)
 - `NewRouter()` — builds a router from an analyzed OpenAPI spec
-- `Spec()`, `SwaggerUI()`, `RapiDoc()` — spec and documentation serving middleware
+
+Standalone server middleware (`server-middleware` module):
+
+- `mediatype.MediaType`, `mediatype.Set` — typed RFC 7231 media-type values + asymmetric matching
+- `negotiate.ContentType()`, `negotiate.ContentEncoding()` — `Accept` / `Accept-Encoding` selection (honours MIME parameters by default; opt out with `WithIgnoreParameters`)
+- `docui.SwaggerUI()`, `docui.RapiDoc()`, `docui.Redoc()`, `docui.ServeSpec()` — stdlib-only doc-UI and spec-serving handlers
 
 ### Dependencies
 
@@ -91,3 +97,7 @@ Key direct dependencies (`go.mod`):
   each stage composable via `middleware.Builder`.
 - **OpenTracing kept in a separate module**: avoids pulling the OpenTracing dependency
   into consumers that only need the core runtime or use OpenTelemetry directly.
+- **`server-middleware` extracted as a separate module**: lets any `net/http` application
+  reuse the negotiation, media-type, and doc-UI primitives without inheriting the OpenAPI
+  spec/loads/validate dependency tree. The root `middleware` package keeps deprecated
+  shims for source compatibility.

.github/copilot-instructions.md

@@ -13,17 +13,18 @@ This is a mono-repo with a `go.work` workspace:
 | Module | Purpose |
 |--------|---------|
 | `.` (root) | Core runtime library |
-| `client-middleware/opentracing` | Optional OpenTracing middleware for client transport |
+| `server-middleware` | Standalone, dependency-free server middleware (`mediatype`, `negotiate`, `negotiate/header`, `docui`) |
+| `client-middleware/opentracing` | OpenTracing middleware for client transport (compatibility module; prefer the OpenTelemetry support built into `client.Runtime`) |
 
 ## Package Layout
 
 | Package | Contents |
 |---------|----------|
 | `runtime` (root) | Core interfaces (`Consumer`, `Producer`, `Authenticator`, `Authorizer`, `OperationHandler`), content-type handlers (JSON, XML, CSV, text, bytestream), HTTP helpers |
 | `client` | HTTP client transport (`Runtime`) with TLS, timeouts, proxy, keepalive, OpenTelemetry |
-| `middleware` | Server request lifecycle: routing, content negotiation, parameter binding, validation, security, Swagger UI / RapiDoc |
+| `middleware` | Server request lifecycle: routing, parameter binding, validation, security, operation execution. Doc-UI and negotiation primitives moved to `server-middleware/*`; legacy entry points remain as deprecated shims in `seam.go`. |
 | `middleware/denco` | Internal path-pattern router |
-| `middleware/header` | HTTP header parsing utilities |
+| `middleware/header` | Deprecated shim — re-exports `server-middleware/negotiate/header` |
 | `middleware/untyped` | Untyped (reflection-based) API handling |
 | `security` | Auth implementations: Basic, API Key, Bearer/OAuth2 (with `*Ctx` variants) |
 | `logger` | `Logger` interface; debug via `SWAGGER_DEBUG` or `DEBUG` env vars |
@@ -47,6 +48,7 @@ This is a mono-repo with a `go.work` workspace:
 - Security functions come in pairs (`BasicAuth` / `BasicAuthCtx`) for context propagation.
 - Server middleware pipeline: Router → Binder → Validator → Security → Executor → Responder.
 - OpenTracing lives in a separate module to avoid pulling its dependency into the core.
+- `server-middleware` is a separate module so any `net/http` app can use negotiation, media-type, and doc-UI primitives without inheriting the OpenAPI spec/loads/validate tree.
 
 ## Dependencies
 

client-middleware/opentracing/README.md

@@ -0,0 +1,72 @@
+# client-middleware/opentracing
+
+[![GoDoc][godoc-badge]][godoc-url]
+
+OpenTracing instrumentation for the `go-openapi/runtime` client transport.
+
+> **Compatibility module.** This module exists solely to support users who
+> still depend on the legacy [OpenTracing API][opentracing-url] and have not
+> yet migrated to OpenTelemetry. New code should use the **OpenTelemetry
+> tracing built into [`client.Runtime`](../../client)** directly — it
+> requires no extra wrapper.
+>
+> The OpenTracing project has been archived since 2022 in favour of
+> OpenTelemetry. We expect to keep this module compiling and passing tests,
+> but it will not gain new features.
+
+It is published as a **separate Go module** so that the
+`opentracing-go` dependency stays out of the main runtime's import graph —
+projects on OpenTelemetry pay no cost for it.
+
+## Install
+
+```sh
+go get github.com/go-openapi/runtime/client-middleware/opentracing
+```
+
+## Usage
+
+`WithOpenTracing` wraps a `client.Runtime` and starts a child span for each
+outgoing operation, provided the operation's `context.Context` already
+carries a parent span. If no parent span is found in the context, the call
+is forwarded unchanged.
+
+```go
+import (
+    "github.com/go-openapi/runtime/client"
+    otmw "github.com/go-openapi/runtime/client-middleware/opentracing"
+)
+
+rt := client.New("api.example.com", "/v1", []string{"https"})
+transport := otmw.WithOpenTracing(rt)
+
+// pass `transport` (a runtime.ClientTransport) to your generated client
+```
+
+Per-request tags can be added through the variadic `opentracing.StartSpanOption`
+arguments:
+
+```go
+transport := otmw.WithOpenTracing(rt, opentracing.Tag{Key: "service", Value: "billing"})
+```
+
+## Migrating to OpenTelemetry
+
+The main `client.Runtime` already emits OpenTelemetry spans; no wrapper is
+needed. Users coming from this module typically:
+
+1. Replace the `opentracing-go` `Tracer` setup with an OpenTelemetry
+   `TracerProvider`.
+2. Drop the `WithOpenTracing` wrapper — instrument the `client.Runtime` directly.
+3. Remove the import of this module.
+
+See the [main runtime README](../../README.md) for the OpenTelemetry
+configuration entry points.
+
+## License
+
+[Apache-2.0](../../LICENSE).
+
+[godoc-badge]: https://pkg.go.dev/badge/github.com/go-openapi/runtime/client-middleware/opentracing
+[godoc-url]: https://pkg.go.dev/github.com/go-openapi/runtime/client-middleware/opentracing
+[opentracing-url]: https://github.com/opentracing/opentracing-go

server-middleware/README.md

@@ -0,0 +1,60 @@
+# server-middleware
+
+[![GoDoc][godoc-badge]][godoc-url]
+
+Standalone, dependency-free server-side middleware utilities for OpenAPI applications.
+
+This module is part of the [`go-openapi/runtime`][runtime-url] toolkit, but is
+maintained as a **separate Go module** so it can be used by any `net/http`
+application — including ones that have no OpenAPI spec at all. It carries no
+transitive dependency on `go-openapi/spec`, `go-openapi/loads`, or
+`go-openapi/validate`; only the standard library and (for tests)
+`go-openapi/testify/v2`.
+
+## Packages
+
+| Package | Purpose |
+|---------|---------|
+| [`mediatype`](./mediatype) | Typed RFC 7231 / RFC 2045 media-type values (`MediaType`, `Set`) and asymmetric matching used by both server-side validation and `Accept`-header negotiation. |
+| [`negotiate`](./negotiate) | Server-side HTTP content negotiation: select the response `Content-Type` from `Accept`, and the response `Content-Encoding` from `Accept-Encoding`. Honours MIME parameters by default; opt out with `WithIgnoreParameters`. |
+| [`negotiate/header`](./negotiate/header) | Low-level RFC-7231 header parsing primitives reused by `negotiate`. Exported for callers that need raw `Accept`/`Accept-Encoding` parsing without the typed media-type layer. |
+| [`docui`](./docui) | Stdlib-only HTTP middlewares that serve OpenAPI documentation UIs (Swagger UI, ReDoc, RapiDoc) and the spec document itself. Mountable on any `net/http` mux. |
+
+## Install
+
+```sh
+go get github.com/go-openapi/runtime/server-middleware
+```
+
+## Quick start — content negotiation
+
+```go
+import "github.com/go-openapi/runtime/server-middleware/negotiate"
+
+offers := []string{"application/json", "application/xml"}
+chosen := negotiate.ContentType(r.Header, offers, "application/json")
+w.Header().Set("Content-Type", chosen)
+```
+
+## Quick start — serving Swagger UI
+
+```go
+import "github.com/go-openapi/runtime/server-middleware/docui"
+
+handler := docui.SwaggerUI(docui.WithSpecURL("/swagger.json"), docui.WithBasePath("/docs"))
+http.Handle("/docs/", handler)
+```
+
+## Further reading
+
+- [`docs/MEDIA_TYPES.md`](../docs/MEDIA_TYPES.md) — the full server-side
+  selection algorithm and its asymmetric matching rules.
+- Full API reference on [pkg.go.dev][godoc-url].
+
+## License
+
+[Apache-2.0](../LICENSE).
+
+[runtime-url]: https://github.com/go-openapi/runtime
+[godoc-badge]: https://pkg.go.dev/badge/github.com/go-openapi/runtime/server-middleware
+[godoc-url]: https://pkg.go.dev/github.com/go-openapi/runtime/server-middleware