docs(xrpc-server): flesh out the readme

packages/servers/xrpc-server-bun/README.md

···
 # @atcute/xrpc-server-bun
 
-Bun WebSocket adapter for `@atcute/xrpc-server`.
+Bun WebSocket adapter for [`@atcute/xrpc-server`](../xrpc-server/).
 
 ```sh
 npm install @atcute/xrpc-server-bun
 ```
+
+see the [subscriptions section](../xrpc-server/#subscriptions) in the main package for usage details.
 
 ```ts
 import { XRPCRouter } from '@atcute/xrpc-server';
 import { createBunWebSocket } from '@atcute/xrpc-server-bun';
 
-import { ComAtprotoSyncSubscribeRepos } from './lexicons/index.js';
+import { ComExampleSubscribe } from './lexicons/index.js';
 
-const { adapter, wrap } = createBunWebSocket();
-const router = new XRPCRouter({ websocket: adapter });
+const ws = createBunWebSocket();
+const router = new XRPCRouter({ websocket: ws.adapter });
 
-router.addSubscription(ComAtprotoSyncSubscribeRepos.mainSchema, {
+router.addSubscription(ComExampleSubscribe.mainSchema, {
 	async *handler({ params, signal }) {
 		while (!signal.aborted) {
 			yield {
···
 	},
 });
 
-export default router satisfies Bun.Serve;
+export default ws.wrap(router);
 ```

packages/servers/xrpc-server-cloudflare/README.md

···
 # @atcute/xrpc-server-cloudflare
 
-Cloudflare Workers WebSocket adapter for `@atcute/xrpc-server`.
+Cloudflare Workers WebSocket adapter for [`@atcute/xrpc-server`](../xrpc-server/).
 
 ```sh
 npm install @atcute/xrpc-server-cloudflare
 ```
+
+see the [subscriptions section](../xrpc-server/#subscriptions) in the main package for usage details.
 
 ```ts
 import { XRPCRouter } from '@atcute/xrpc-server';
 import { createCloudflareWebSocket } from '@atcute/xrpc-server-cloudflare';
 
-import { ComAtprotoSyncSubscribeRepos } from './lexicons/index.js';
+import { ComExampleSubscribe } from './lexicons/index.js';
 
 const adapter = createCloudflareWebSocket();
 const router = new XRPCRouter({ websocket: adapter });
 
-router.addSubscription(ComAtprotoSyncSubscribeRepos.mainSchema, {
+router.addSubscription(ComExampleSubscribe.mainSchema, {
 	async *handler({ params, signal }) {
 		while (!signal.aborted) {
 			yield {

packages/servers/xrpc-server-deno/README.md

···
 # @atcute/xrpc-server-deno
 
-Deno WebSocket adapter for `@atcute/xrpc-server`.
+Deno WebSocket adapter for [`@atcute/xrpc-server`](../xrpc-server/).
 
 ```sh
-npm install @atcute/xrpc-server-deno
+deno add jsr:@aspect/xrpc-server-deno
 ```
 
+see the [subscriptions section](../xrpc-server/#subscriptions) in the main package for usage details.
+
 ```ts
 import { XRPCRouter } from '@atcute/xrpc-server';
 import { createDenoWebSocket } from '@atcute/xrpc-server-deno';
 
-import { ComAtprotoSyncSubscribeRepos } from './lexicons/index.ts';
+import { ComExampleSubscribe } from './lexicons/index.ts';
 
 const adapter = createDenoWebSocket();
 const router = new XRPCRouter({ websocket: adapter });
 
-router.addSubscription(ComAtprotoSyncSubscribeRepos.mainSchema, {
+router.addSubscription(ComExampleSubscribe.mainSchema, {
 	async *handler({ params, signal }) {
 		while (!signal.aborted) {
 			yield {

packages/servers/xrpc-server-node/README.md

···
 # @atcute/xrpc-server-node
 
-Node.js WebSocket adapter for `@atcute/xrpc-server`.
+Node.js WebSocket adapter for [`@atcute/xrpc-server`](../xrpc-server/).
 
 ```sh
 npm install @atcute/xrpc-server-node
 ```
+
+see the [subscriptions section](../xrpc-server/#subscriptions) in the main package for usage details.
 
 ```ts
 import { serve } from '@hono/node-server';
 import { XRPCRouter } from '@atcute/xrpc-server';
 import { createNodeWebSocket } from '@atcute/xrpc-server-node';
 
-const { adapter, injectWebSocket } = createNodeWebSocket();
-const router = new XRPCRouter({ websocket: adapter });
+import { ComExampleSubscribe } from './lexicons/index.js';
+
+const ws = createNodeWebSocket();
+const router = new XRPCRouter({ websocket: ws.adapter });
 
-router.addSubscription(ComAtprotoSyncSubscribeRepos.mainSchema, {
+router.addSubscription(ComExampleSubscribe.mainSchema, {
 	async *handler({ params, signal }) {
 		while (!signal.aborted) {
 			yield {
···
 	},
 });
 
-const server = serve(
-	{
-		fetch: router.fetch,
-		port: 3000,
-	},
-	(info) => {
-		console.log(`Listening on port ${info.port}`);
-	},
-);
+const server = serve({ fetch: router.fetch, port: 3000 }, (info) => {
+	console.log(`listening on port ${info.port}`);
+});
 
-injectWebSocket(server, router);
+ws.injectWebSocket(server, router);
 ```

packages/servers/xrpc-server/README.md

···
 npm install @atcute/xrpc-server
 ```
 
-## quick start
+## prerequisites
 
 this framework relies on schemas generated by `@atcute/lex-cli`, you'd need to follow its
 [quick start guide](../../lexicons/lex-cli) on how to set it up.
 
-for this example, we'll define a very simple query operation, one that returns a message greeting
-the name that's provided to it:
+for these examples, we'll use a simple query operation that greets a name:
 
 ```json
 // file: lexicons/com/example/greet.json
···
 				"type": "params",
 				"required": ["name"],
 				"properties": {
-					"name": {
-						"type": "string"
-					}
+					"name": { "type": "string" }
 				}
 			},
 			"output": {
···
 					"type": "object",
 					"required": ["message"],
 					"properties": {
-						"message": {
-							"type": "string"
-						}
+						"message": { "type": "string" }
 					}
 				}
 			}
···
 }
 ```
 
-now we can build a server using the TypeScript schemas:
+## usage
+
+### handling requests
+
+use `addQuery()` for queries (GET) and `addProcedure()` for procedures (POST). handlers receive
+typed `params` and `input`, and return responses using the `json()` helper:
 
 ```ts
-// file: src/index.js
 import { XRPCRouter, json } from '@atcute/xrpc-server';
 import { cors } from '@atcute/xrpc-server/middlewares/cors';
 
-import { ComExampleGreet } from './lexicons/index.js';
+import { ComExampleGreet, ComExampleCreatePost } from './lexicons/index.js';
 
 const router = new XRPCRouter({ middlewares: [cors()] });
 
-router.add(ComExampleGreet.mainSchema, {
-	async handler({ params: { name } }) {
-		return json({ message: `hello ${name}!` });
+router.addQuery(ComExampleGreet.mainSchema, {
+	async handler({ params }) {
+		return json({ message: `hello ${params.name}!` });
+	},
+});
+
+router.addProcedure(ComExampleCreatePost.mainSchema, {
+	async handler({ input }) {
+		const post = await db.createPost(input);
+		return json(post);
 	},
 });
 
 export default router;
 ```
 
+### serving the router
+
 on Deno, Bun or Cloudflare Workers, you can export the router directly and expect it to work out of
 the box.
 
-but for Node.js, you'll need the [`@hono/node-server`][hono-node-server] adapter as the router works
+for Node.js, you'll need the [`@hono/node-server`][hono-node-server] adapter as the router works
 with standard Web Request/Response:
 
 [hono-node-server]: https://github.com/honojs/node-server
 
 ```ts
-// file: src/index.js
 import { XRPCRouter } from '@atcute/xrpc-server';
 import { serve } from '@hono/node-server';
 
 const router = new XRPCRouter();
 
-// ... handler code ...
+// ... add handlers ...
+
+serve({ fetch: router.fetch, port: 3000 }, (info) => {
+	console.log(`listening on port ${info.port}`);
+});
+```
+
+### error handling
+
+throw `XRPCError` in handlers to return error responses:
+
+```ts
+import { XRPCError } from '@atcute/xrpc-server';
+
+router.addQuery(ComExampleGetPost.mainSchema, {
+	async handler({ params, request }) {
+		const session = await getSession(request);
+		if (!session) {
+			throw new XRPCError({ status: 401, error: 'AuthenticationRequired' });
+		}
+
+		const post = await db.getPost(params.uri);
+		if (!post) {
+			throw new XRPCError({ status: 400, error: 'InvalidRequest', description: `post not found` });
+		}
+
+		return json(post);
+	},
+});
+```
+
+convenience subclasses are also available: `InvalidRequestError`, `AuthRequiredError`,
+`ForbiddenError`, `RateLimitExceededError`, `InternalServerError`, `UpstreamFailureError`,
+`NotEnoughResourcesError`, `UpstreamTimeoutError`.
+
+### subscriptions
+
+subscriptions provide real-time streaming over WebSocket. they require a runtime-specific adapter:
+
+| runtime            | adapter package                                                |
+| ------------------ | -------------------------------------------------------------- |
+| Bun                | [`@atcute/xrpc-server-bun`](../xrpc-server-bun/)               |
+| Node.js            | [`@atcute/xrpc-server-node`](../xrpc-server-node/)             |
+| Deno               | [`@atcute/xrpc-server-deno`](../xrpc-server-deno/)             |
+| Cloudflare Workers | [`@atcute/xrpc-server-cloudflare`](../xrpc-server-cloudflare/) |
+
+here's an example using Bun:
+
+```ts
+import { XRPCRouter } from '@atcute/xrpc-server';
+import { createBunWebSocket } from '@atcute/xrpc-server-bun';
+
+import { ComExampleSubscribe } from './lexicons/index.js';
+
+const ws = createBunWebSocket();
+
+const router = new XRPCRouter({ websocket: ws.adapter });
+
+router.addSubscription(ComExampleSubscribe.mainSchema, {
+	async *handler({ params, signal }) {
+		// yield messages until the client disconnects
+		while (!signal.aborted) {
+			const events = await getNewEvents(params.cursor);
+
+			for (const event of events) {
+				yield event;
+			}
 
-serve(
-	{
-		fetch: router.fetch,
-		port: 3000,
+			await sleep(1000);
+		}
 	},
-	(info) => {
-		console.log(`listening on port ${info.port}`);
+});
+
+export default ws.wrap(router);
+```
+
+the handler is an async generator that yields messages. each yielded value is encoded as a CBOR
+frame and sent to the client. the `signal` is aborted when the client disconnects.
+
+for subscription errors, use `XRPCSubscriptionError`:
+
+```ts
+import { XRPCSubscriptionError } from '@atcute/xrpc-server';
+
+router.addSubscription(ComExampleSubscribe.mainSchema, {
+	async *handler({ params }) {
+		if (params.cursor && isCursorTooOld(params.cursor)) {
+			throw new XRPCSubscriptionError({
+				error: 'FutureCursor',
+				description: `cursor is too old`,
+			});
+		}
+
+		// ...
+	},
+});
+```
+
+### service authentication
+
+the `@atcute/xrpc-server/auth` subpackage provides utilities for service-to-service authentication
+using JWTs.
+
+verifying incoming JWTs:
+
+```ts
+import { AuthRequiredError } from '@atcute/xrpc-server';
+import { ServiceJwtVerifier, type VerifiedJwt } from '@atcute/xrpc-server/auth';
+import {
+	CompositeDidDocumentResolver,
+	PlcDidDocumentResolver,
+	WebDidDocumentResolver,
+} from '@atcute/identity-resolver';
+
+const jwtVerifier = new ServiceJwtVerifier({
+	serviceDid: 'did:web:my-service.example.com',
+	resolver: new CompositeDidDocumentResolver({
+		methods: {
+			plc: new PlcDidDocumentResolver(),
+			web: new WebDidDocumentResolver(),
+		},
+	}),
+});
+
+const verifyServiceAuth = async (request: Request, lxm: string): Promise<VerifiedJwt> => {
+	const authHeader = request.headers.get('authorization');
+	if (!authHeader?.startsWith('Bearer ')) {
+		throw new AuthRequiredError({ description: `missing or invalid authorization header` });
+	}
+
+	const result = await jwtVerifier.verify(authHeader.slice(7), { lxm });
+	if (!result.ok) {
+		throw new AuthRequiredError({ description: result.error.description });
+	}
+
+	return result.value;
+};
+
+router.addQuery(ComExampleProtectedEndpoint.mainSchema, {
+	async handler({ request }) {
+		const auth = await verifyServiceAuth(request, 'com.example.protectedEndpoint');
+		return json({ caller: auth.issuer });
 	},
-);
+});
+```
+
+creating outgoing JWTs:
+
+```ts
+import { createServiceJwt } from '@atcute/xrpc-server/auth';
+
+const jwt = await createServiceJwt({
+	keypair: myServiceKeypair,
+	issuer: 'did:web:my-service.example.com',
+	audience: 'did:plc:targetservice',
+	lxm: 'com.example.someEndpoint',
+});
+
+// use jwt in Authorization header when calling other services
 ```
 
-## internal calls
+### internal calls
 
 you can make typed calls to your own endpoints using `@atcute/client`: