Give the README a clearer technical story

SECURITY.md

@@ -19,6 +19,6 @@ alongside it.
 
 ## What the library does and does not do
 
-The README's [Security](README.md#security) section lists what the library does by default (exception redaction, nesting limit, document and batch limits in the core, request-size limit on the Kestrel host) and what it leaves to the host.
+The [security reference](docs/reference.md#security) lists what the library does by default (exception redaction, nesting limit, document and batch limits in the core, request-size limit on the Kestrel host) and what it leaves to the host.
 
 Authentication, connection identity, TLS, rate limiting, request logging and deadlines belong to the host. HTTP hosts use ASP.NET Core middleware and endpoint metadata (`RequireAuthorization`, `UseRateLimiter`, the request-timeouts middleware); raw connections bypass that pipeline, so listen on loopback or a Unix socket, authenticate in front of them and use listener limits. Methods enforce authorisation that depends on parameter values. Core limits constrain admitted documents and batches, while transports bound bytes during receipt. Authentication and credential handling remain application responsibilities.

docs/serializers.md

@@ -63,7 +63,7 @@ System.Text.Json API next to a lenient Json.NET one for old clients; the AspNetC
 `MapJsonRpc(pattern, options)` overload maps one endpoint per session). Use per-call when the transport
 negotiates it (a header, a route, a protocol version). The process-wide default is for the common case
 of one serializer everywhere. This order applies to the serializer only; error and processing handlers
-are per session, see the main README's [Configuration](../README.md#configuration) table.
+are per session, see the API reference's [Configuration](reference.md#configuration) table.
 
 Construct a serializer once and share it: serializers must be thread-safe. The synchronous fast path
 keeps an envelope reader in per-thread scratch storage, reused while the serializer instance stays the

samples/EmbeddedHost/README.md

@@ -24,4 +24,4 @@ dotnet run -- ui             # the pipe host, methods run on the owning thread
 curl -s -X POST http://127.0.0.1:5078/rpc/ -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"add","params":[1,2],"id":1}'
 ```
 
-The README's [Hosting](../../README.md#hosting) section walks through the three files.
+The [embedded hosting reference](../../docs/reference.md#embedded-http-without-aspnet-core-a-pipe-without-kestrel-a-thread-that-owns-the-state) walks through the three files.

site/README.md

@@ -5,6 +5,7 @@ The pages at https://astn.github.io/JSON-RPC.NET/ are built from the Markdown fi
 | Page | Source |
 | --- | --- |
 | Overview | `README.md` |
+| API reference | `docs/reference.md` |
 | Serializers | `docs/serializers.md` |
 | ASP.NET Core hosting | `AustinHarris.JsonRpc.AspNetCore/README.md` |
 | Json.NET serializer | `AustinHarris.JsonRpc.Newtonsoft/README.md` |

site/build.py

@@ -45,6 +45,8 @@
 PAGES = [
     ("index.html", "README.md", "JSON-RPC.NET", "Overview", "Guide",
      "A high performance JSON-RPC 2.0 server for .NET: bytes in, bytes out, pluggable serializers, Kestrel hosting."),
+    ("reference.html", "docs/reference.md", "API and hosting reference", "API reference", "Guide",
+     "Detailed binding, hosting, async, session, configuration and security behavior for JSON-RPC.NET."),
     ("changelog.html", "CHANGELOG.md", "What is new", "What is new", "Guide",
      "Release notes for every version: what 2.0 adds, changes, removes and fixes, and the 1.x history."),
     ("upgrading.html", "docs/upgrading.md", "Upgrading from 1.x", "Upgrading from 1.x", "Guide",

site/page.typ

@@ -36,6 +36,8 @@
     img: ("void", (attrs) => himg(attrs.at("src", default: ""), alt: attrs.at("alt", default: ""))),
     picture: (attrs, body) => html.elem("picture", body),
     source: ("void", (attrs) => html.elem("source", attrs: attrs)),
+    details: (attrs, body) => html.elem("details", body, attrs: attrs),
+    summary: (attrs, body) => html.elem("summary", body, attrs: attrs),
   ),
 )