resolve comments + sync docs

Author: kevzzsk

docs/api-reference/aixyz-server.mdx

@@ -91,12 +91,15 @@ await server.initialize();
 
 ```typescript title="app/server.ts"
 import { AixyzApp } from "aixyz/app";
+import { SessionPlugin } from "aixyz/app/plugins/session";
 import { IndexPagePlugin } from "aixyz/app/plugins/index-page";
 import { A2APlugin } from "aixyz/app/plugins/a2a";
 import * as agent from "./agent";
 
 const server = new AixyzApp();
 
+// SessionPlugin must be registered first so its middleware runs before other plugins
+await server.withPlugin(new SessionPlugin());
 await server.withPlugin(new IndexPagePlugin());
 await server.withPlugin(new A2APlugin([{ exports: agent }]));
 

docs/api-reference/session-plugin.mdx

@@ -117,20 +117,24 @@ Implement the `SessionStore` interface for Redis, a database, or any KV store:
 
 ```typescript title="app/session.ts"
 import { defineSessionStore } from "aixyz/app/plugins/session";
-import type { SessionStore } from "aixyz/app/plugins/session";
+import type { SessionStore, ListOptions, SetOptions } from "aixyz/app/plugins/session";
 
 class RedisSessionStore implements SessionStore {
   async get(payer: string, key: string) {
     return (await redis.get(`${payer}:${key}`)) ?? undefined;
   }
-  async set(payer: string, key: string, value: string) {
-    await redis.set(`${payer}:${key}`, value);
+  async set(payer: string, key: string, value: string, options?: SetOptions) {
+    if (options?.ttlMs) {
+      await redis.set(`${payer}:${key}`, value, "PX", options.ttlMs);
+    } else {
+      await redis.set(`${payer}:${key}`, value);
+    }
   }
   async delete(payer: string, key: string) {
     return (await redis.del(`${payer}:${key}`)) > 0;
   }
-  async list(payer: string) {
-    // scan for keys matching payer prefix
+  async list(payer: string, options?: ListOptions) {
+    // scan for keys matching payer prefix, apply options.prefix/limit/cursor
     return {
       entries: {
         /* ... */

docs/getting-started/payments.mdx

@@ -137,3 +137,19 @@ export const facilitator = new HTTPFacilitatorClient({
 ```
 
 See the [BYO Facilitator template](/templates/advanced/with-custom-facilitator) for a working example.
+
+## Payer Identity and Sessions
+
+Every verified x402 payment identifies the payer by their wallet address. `SessionPlugin` (auto-registered by the build pipeline) gives each payer isolated key-value storage accessible via `getSession()`:
+
+```typescript
+import { getSession } from "aixyz/app/plugins/session";
+
+const session = getSession();
+if (session) {
+  await session.set("preference", "dark-mode");
+  const payer = session.payer; // "0x1234..."
+}
+```
+
+This works in both A2A agent handlers and MCP tool handlers. See [SessionPlugin](/api-reference/session-plugin) for the full API and custom store configuration.

docs/getting-started/project-structure.mdx

@@ -35,6 +35,11 @@ An aixyz agent is defined by a small set of files in a standard layout. Run `aix
               description: "Custom x402 facilitator",
               badge: { text: "optional override", color: "purple" },
             },
+            {
+              name: "session.ts",
+              description: "Custom session store",
+              badge: { text: "optional override", color: "purple" },
+            },
             {
               name: "erc-8004.ts",
               description: "ERC-8004 identity registration",
@@ -126,6 +131,7 @@ An aixyz agent is defined by a small set of files in a standard layout. Run `aix
 | `app/tools/*.ts`    | No       | Tool implementations, auto-discovered by the build                                |
 | `app/server.ts`     | No       | [Custom server](/api-reference/aixyz-server) — overrides auto-generation entirely |
 | `app/accepts.ts`    | No       | [Custom x402 facilitator](/api-reference/accepts) for payment verification        |
+| `app/session.ts`    | No       | [Custom session store](/api-reference/session-plugin) override for SessionPlugin  |
 | `app/erc-8004.ts`   | No       | ERC-8004 identity registration and trust config                                   |
 | `app/agent.test.ts` | No       | Agent tests using `bun:test`                                                      |
 | `app/icon.svg`      | No       | Agent icon served as a static asset                                               |
@@ -141,7 +147,8 @@ The build pipeline scans the `app/` directory to auto-generate a server:
 2. Imports `app/agent.ts` for the main agent definition (if present)
 3. Discovers all `.ts` files in `app/agents/` for sub-agents (each gets its own A2A endpoint)
 4. Discovers all `.ts` files in `app/tools/` (excluding `_` prefixed files)
-5. Wires up A2A (when agents exist), MCP (when tools exist), and x402 endpoints automatically
+5. Registers `SessionPlugin` (with custom store from `app/session.ts` if present)
+6. Wires up A2A (when agents exist), MCP (when tools exist), and x402 endpoints automatically
 
 The result is a server exposing:
 

docs/protocols/mcp.mdx

@@ -58,6 +58,20 @@ await server.withPlugin(
 );
 ```
 
+## Session Integration
+
+Paid MCP tools automatically get session context. When a tool is invoked with x402 payment, `getSession()` returns the payer-scoped session inside the tool handler — no additional configuration needed.
+
+```typescript
+import { getSession } from "aixyz/app/plugins/session";
+
+// Inside an MCP tool handler:
+const session = getSession();
+await session?.set("key", "value"); // stored per-payer
+```
+
+See [SessionPlugin](/api-reference/session-plugin) for the full API.
+
 ## Payment-Gated Tools
 
 Tools with `accepts.scheme === "exact"` require [x402 payment](/protocols/x402) via `@x402/mcp`. The payment wrapper is applied automatically when you provide an `accepts` configuration during registration.
@@ -81,6 +95,9 @@ await server.withPlugin(
   <Card title="Tools" icon="folder-tree" href="/api-reference/tools">
     How tools are defined in the app/ directory.
   </Card>
+  <Card title="SessionPlugin" icon="database" href="/api-reference/session-plugin">
+    Payer-scoped storage for MCP tools.
+  </Card>
   <Card title="A2A Protocol" icon="diagram-project" href="/protocols/a2a">
     Agent discovery and communication via A2A.
   </Card>

packages/aixyz/app/plugin.ts

@@ -1,5 +1,4 @@
 import type { HttpMethod, RouteHandler, RouteEntry, RouteOptions, Middleware } from "./types";
-import type { AcceptsX402 } from "../accepts";
 import type {
   PaymentGateway,
   BeforeVerifyHook,

packages/aixyz/app/plugins/mcp.ts

@@ -111,7 +111,7 @@ export class MCPPlugin extends BasePlugin {
   }
 
   async initialize(ctx: InitializeContext): Promise<void> {
-    this.sessionPlugin = ctx.getPlugin<SessionPlugin>("session") as SessionPlugin | undefined;
+    this.sessionPlugin = ctx.getPlugin<SessionPlugin>("session");
 
     if (!ctx.payment) return;