aixyz 0.34.0 → 0.36.0

package/app/plugins/session/memory.ts

@@ -0,0 +1,206 @@
+import type { SessionStore, SetOptions, ListOptions, ListResult } from "./index";
+
+// ── Types ─────────────────────────────────────────────────────────────
+
+export interface InMemorySessionStoreOptions {
+  /** Maximum number of entries across all payers. Default: 10 000. */
+  maxEntries?: number;
+  /** Time-to-live in milliseconds (sliding window). 0 = no expiry. Default: 3 600 000 (1 h). */
+  ttlMs?: number;
+}
+
+interface Entry {
+  value: string;
+  payer: string;
+  key: string;
+  expiresAt: number; // 0 = never expires
+  ttlMs: number; // effective TTL used when refreshing on get(); 0 = no expiry
+}
+
+// ── Implementation ────────────────────────────────────────────────────
+
+/**
+ * Production-ready in-memory {@link SessionStore} with LRU eviction and
+ * optional TTL.
+ *
+ * - **LRU eviction** — backed by `Map` insertion-order. When `maxEntries`
+ *   is reached, the least-recently-used entry is evicted.
+ * - **Sliding-window TTL** — `get()` refreshes the expiry timer.
+ *   Expired entries are lazily removed on read; no background timers.
+ * - **OOM-safe** — `maxEntries` is a hard cap. Memory usage is bounded
+ *   regardless of TTL or access patterns.
+ */
+export class InMemorySessionStore implements SessionStore {
+  private readonly maxEntries: number;
+  private readonly ttlMs: number;
+
+  /** Flat LRU map. Key = `${payer}:${key}`. Insertion order = access order. */
+  private readonly entries = new Map<string, Entry>();
+  /** Secondary index: payer → set of composite keys (for efficient `list`). */
+  private readonly payerIndex = new Map<string, Set<string>>();
+
+  constructor(options?: InMemorySessionStoreOptions) {
+    this.maxEntries = options?.maxEntries ?? 10_000;
+    this.ttlMs = options?.ttlMs ?? 3_600_000;
+    if (this.maxEntries < 1) throw new Error("maxEntries must be >= 1");
+    if (this.ttlMs < 0) throw new Error("ttlMs must be >= 0");
+  }
+
+  async get(payer: string, key: string): Promise<string | undefined> {
+    const ck = compositeKey(payer, key);
+    const entry = this.entries.get(ck);
+    if (!entry) return undefined;
+
+    if (this.isExpired(entry)) {
+      this.removeEntry(ck, entry);
+      return undefined;
+    }
+
+    // LRU touch: move to end + refresh TTL using the entry's own TTL
+    this.entries.delete(ck);
+    entry.expiresAt = this.expiryFor(entry.ttlMs);
+    this.entries.set(ck, entry);
+
+    return entry.value;
+  }
+
+  async set(payer: string, key: string, value: string, options?: SetOptions): Promise<void> {
+    const ck = compositeKey(payer, key);
+
+    // If overwriting, remove first so re-insert lands at the end.
+    const existing = this.entries.get(ck);
+    if (existing) {
+      this.entries.delete(ck);
+    }
+
+    // Evict LRU entry if at capacity.
+    if (this.entries.size >= this.maxEntries) {
+      const oldest = this.entries.keys().next();
+      if (!oldest.done) {
+        const oldestEntry = this.entries.get(oldest.value)!;
+        this.removeEntry(oldest.value, oldestEntry);
+      }
+    }
+
+    const effectiveTtl = options?.ttlMs ?? this.ttlMs;
+    const entry: Entry = { value, payer, key, expiresAt: this.expiryFor(effectiveTtl), ttlMs: effectiveTtl };
+    this.entries.set(ck, entry);
+
+    // Update payer index.
+    let idx = this.payerIndex.get(payer);
+    if (!idx) {
+      idx = new Set();
+      this.payerIndex.set(payer, idx);
+    }
+    idx.add(ck);
+  }
+
+  async delete(payer: string, key: string): Promise<boolean> {
+    const ck = compositeKey(payer, key);
+    const entry = this.entries.get(ck);
+    if (!entry) return false;
+    this.removeEntry(ck, entry);
+    return true;
+  }
+
+  async list(payer: string, options?: ListOptions): Promise<ListResult> {
+    const idx = this.payerIndex.get(payer);
+    if (!idx) return { entries: {} };
+
+    const prefix = options?.prefix;
+    const limit = options?.limit && options.limit > 0 ? options.limit : Infinity;
+    const keysOnly = options?.keysOnly ?? false;
+    const cursor = options?.cursor;
+
+    const result: Record<string, string> = {};
+    let count = 0;
+    let pastCursor = !cursor;
+    let lastCk: string | undefined;
+    let hasMore = false;
+
+    for (const ck of idx) {
+      const entry = this.entries.get(ck);
+      if (!entry) {
+        idx.delete(ck);
+        continue;
+      }
+      if (this.isExpired(entry)) {
+        this.removeEntry(ck, entry);
+        continue;
+      }
+
+      // Skip until we pass the cursor position.
+      if (!pastCursor) {
+        if (ck === cursor) pastCursor = true;
+        continue;
+      }
+
+      // Apply prefix filter.
+      if (prefix && !entry.key.startsWith(prefix)) continue;
+
+      if (count >= limit) {
+        hasMore = true;
+        break;
+      }
+
+      result[entry.key] = keysOnly ? "" : entry.value;
+      lastCk = ck;
+      count++;
+    }
+
+    if (idx.size === 0) this.payerIndex.delete(payer);
+    return { entries: result, cursor: hasMore ? lastCk : undefined };
+  }
+
+  async getMany(payer: string, keys: string[]): Promise<Record<string, string | undefined>> {
+    const result: Record<string, string | undefined> = {};
+    for (const key of keys) {
+      result[key] = await this.get(payer, key);
+    }
+    return result;
+  }
+
+  async setMany(payer: string, entries: Record<string, string>, options?: SetOptions): Promise<void> {
+    for (const [key, value] of Object.entries(entries)) {
+      await this.set(payer, key, value, options);
+    }
+  }
+
+  async deleteMany(payer: string, keys: string[]): Promise<number> {
+    let count = 0;
+    for (const key of keys) {
+      if (await this.delete(payer, key)) count++;
+    }
+    return count;
+  }
+
+  async close(): Promise<void> {
+    this.entries.clear();
+    this.payerIndex.clear();
+  }
+
+  // ── Internals ───────────────────────────────────────────────────────
+
+  private removeEntry(ck: string, entry: Entry): void {
+    this.entries.delete(ck);
+    const idx = this.payerIndex.get(entry.payer);
+    if (idx) {
+      idx.delete(ck);
+      if (idx.size === 0) this.payerIndex.delete(entry.payer);
+    }
+  }
+
+  private isExpired(entry: Entry): boolean {
+    return entry.expiresAt > 0 && Date.now() > entry.expiresAt;
+  }
+
+  private expiryFor(ttlMs: number): number {
+    return ttlMs > 0 ? Date.now() + ttlMs : 0;
+  }
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────
+
+function compositeKey(payer: string, key: string): string {
+  return `${payer}:${key}`;
+}

package/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 }]));
 

package/docs/api-reference/session-plugin.mdx

@@ -0,0 +1,192 @@
+---
+title: "SessionPlugin"
+description: "Payer-scoped key-value storage gated by x402 payment identity"
+---
+
+## Overview
+
+`SessionPlugin` provides per-payer key-value storage for aixyz agents. Each x402 signer gets an isolated session -- two different payers never see each other's data. Sessions are accessed via `getSession()` using `AsyncLocalStorage`, so tools don't need to thread payer identity through function parameters.
+
+SessionPlugin is **always registered** by the build pipeline. To use a custom storage backend, create an `app/session.ts` file.
+
+```typescript
+import { getSession, getPayer } from "aixyz/app/plugins/session";
+```
+
+## Setup
+
+SessionPlugin is auto-registered when `aixyz build` or `aixyz dev` generates the server entrypoint. No manual setup is needed for the default in-memory store.
+
+To use a custom store (Redis, database, etc.), create `app/session.ts`:
+
+```typescript title="app/session.ts"
+import { defineSessionStore, InMemorySessionStore } from "aixyz/app/plugins/session";
+
+export default defineSessionStore(new InMemorySessionStore());
+```
+
+The build pipeline detects `app/session.ts` and passes it to `SessionPlugin({ store: sessionStore })`. If no `app/session.ts` exists, the default `InMemorySessionStore` is used.
+
+## API
+
+### `getSession()`
+
+Returns the current payer-scoped `Session`, or `undefined` if no x402 payment was made for this request.
+
+```typescript
+import { getSession } from "aixyz/app/plugins/session";
+
+const session = getSession();
+if (!session) {
+  return { error: "No authenticated signer" };
+}
+
+await session.set("key", "value");
+const value = await session.get("key");
+```
+
+### `getPayer()`
+
+Shorthand for `getSession()?.payer`. Returns the x402 signer address or `undefined`.
+
+```typescript
+import { getPayer } from "aixyz/app/plugins/session";
+
+const payer = getPayer(); // "0x1234..."
+```
+
+## Session Interface
+
+All operations are scoped to the current x402 payer automatically.
+
+| Method   | Signature                                                             | Description                                   |
+| -------- | --------------------------------------------------------------------- | --------------------------------------------- |
+| `payer`  | `readonly string`                                                     | The x402 signer address                       |
+| `get`    | `(key: string) => Promise<string \| undefined>`                       | Get a value by key                            |
+| `set`    | `(key: string, value: string, options?: SetOptions) => Promise<void>` | Store a key-value pair                        |
+| `delete` | `(key: string) => Promise<boolean>`                                   | Delete a key, returns whether it existed      |
+| `list`   | `(options?: ListOptions) => Promise<ListResult>`                      | List key-value pairs with optional pagination |
+
+### `SetOptions`
+
+| Field   | Type     | Description                                                          |
+| ------- | -------- | -------------------------------------------------------------------- |
+| `ttlMs` | `number` | Per-key TTL in milliseconds. Overrides store default when supported. |
+
+### `ListOptions`
+
+| Field      | Type      | Description                                       |
+| ---------- | --------- | ------------------------------------------------- |
+| `prefix`   | `string`  | Only return keys starting with this prefix        |
+| `cursor`   | `string`  | Opaque cursor from a previous `list()` call       |
+| `limit`    | `number`  | Maximum number of entries to return               |
+| `keysOnly` | `boolean` | If true, values are omitted (all values are `""`) |
+
+### `ListResult`
+
+| Field     | Type                     | Description                                                         |
+| --------- | ------------------------ | ------------------------------------------------------------------- |
+| `entries` | `Record<string, string>` | The key-value pairs                                                 |
+| `cursor`  | `string \| undefined`    | If present, more results are available. Pass to next `list()` call. |
+
+## InMemorySessionStore
+
+The default store. Uses LRU eviction and optional sliding-window TTL.
+
+- **LRU eviction** -- when `maxEntries` is reached, the least-recently-used entry is evicted
+- **Sliding-window TTL** -- `get()` refreshes the expiry timer. Expired entries are lazily removed on read.
+- **OOM-safe** -- `maxEntries` is a hard cap across all payers
+
+```typescript
+import { InMemorySessionStore } from "aixyz/app/plugins/session";
+
+const store = new InMemorySessionStore({
+  maxEntries: 10_000, // default
+  ttlMs: 3_600_000, // 1 hour default, 0 to disable
+});
+```
+
+| Option       | Type     | Default   | Description                                      |
+| ------------ | -------- | --------- | ------------------------------------------------ |
+| `maxEntries` | `number` | `10000`   | Maximum entries across all payers. Must be >= 1. |
+| `ttlMs`      | `number` | `3600000` | Sliding-window TTL in ms. 0 disables expiry.     |
+
+## Custom Storage Backend
+
+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, 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, 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, options?: ListOptions) {
+    // scan for keys matching payer prefix, apply options.prefix/limit/cursor
+    return {
+      entries: {
+        /* ... */
+      },
+    };
+  }
+}
+
+export default defineSessionStore(new RedisSessionStore());
+```
+
+### `SessionStore` Interface
+
+**Required methods:**
+
+| Method   | Signature                                                                            | Description             |
+| -------- | ------------------------------------------------------------------------------------ | ----------------------- |
+| `get`    | `(payer: string, key: string) => Promise<string \| undefined>`                       | Get a value             |
+| `set`    | `(payer: string, key: string, value: string, options?: SetOptions) => Promise<void>` | Store a value           |
+| `delete` | `(payer: string, key: string) => Promise<boolean>`                                   | Delete a value          |
+| `list`   | `(payer: string, options?: ListOptions) => Promise<ListResult>`                      | List values for a payer |
+
+**Optional methods:**
+
+| Method       | Signature                                                                                 | Description                 |
+| ------------ | ----------------------------------------------------------------------------------------- | --------------------------- |
+| `getMany`    | `(payer: string, keys: string[]) => Promise<Record<string, string \| undefined>>`         | Batch get                   |
+| `setMany`    | `(payer: string, entries: Record<string, string>, options?: SetOptions) => Promise<void>` | Batch set                   |
+| `deleteMany` | `(payer: string, keys: string[]) => Promise<number>`                                      | Batch delete, returns count |
+| `close`      | `() => Promise<void>`                                                                     | Release connections/timers  |
+
+## MCP Integration
+
+Sessions work automatically inside MCP tool handlers. The MCP plugin detects the session plugin and wraps tool execution with the payer context from x402 payment verification.
+
+No additional configuration is needed.
+
+## Constructor Options
+
+```typescript
+new SessionPlugin(options?: SessionPluginOptions)
+```
+
+| Option  | Type           | Default                | Description            |
+| ------- | -------------- | ---------------------- | ---------------------- |
+| `store` | `SessionStore` | `InMemorySessionStore` | Custom storage backend |
+
+<CardGroup cols={2}>
+  <Card title="x402 Payments" icon="credit-card" href="/protocols/x402">
+    Payment protocol that provides payer identity for sessions.
+  </Card>
+  <Card title="x402 Sessions Template" icon="database" href="/templates/advanced/x402-sessions">
+    Working example with session-backed content storage.
+  </Card>
+</CardGroup>

package/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.

package/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:
 

package/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>

package/docs/templates/advanced/x402-sessions.mdx

@@ -0,0 +1,99 @@
+---
+title: "x402 Sessions"
+description: "Template demonstrating payer-scoped session storage with x402 payment identity"
+---
+
+<Info>**Source:** [`examples/x402-sessions`](https://github.com/AgentlyHQ/aixyz/tree/main/examples/x402-sessions)</Info>
+
+## Overview
+
+This template demonstrates `SessionPlugin` -- payer-scoped key-value storage gated by x402 payment identity. Each x402 signer gets isolated storage that persists across requests. Two different payers never see each other's data.
+
+## Project Structure
+
+```
+x402-sessions/
+├── aixyz.config.ts           # Agent metadata and skills
+├── app/
+│   ├── session.ts            # Custom session store (optional)
+│   ├── agent.ts              # Agent definition
+│   ├── accepts.ts            # Custom x402 facilitator
+│   └── tools/
+│       ├── put-content.ts    # Store content in session
+│       └── get-content.ts    # Retrieve content from session
+├── package.json
+└── vercel.json
+```
+
+## Session Store
+
+SessionPlugin is auto-registered by the build pipeline. To customize the store, create `app/session.ts`:
+
+```typescript title="app/session.ts"
+import { defineSessionStore, InMemorySessionStore } from "aixyz/app/plugins/session";
+
+// Use the built-in in-memory store. Replace with Redis, DB, etc. for production.
+export default defineSessionStore(new InMemorySessionStore());
+```
+
+If `app/session.ts` is not present, the default `InMemorySessionStore` is used automatically.
+
+## Using Sessions in Tools
+
+Tools access the session via `getSession()` -- no need to pass payer identity manually:
+
+```typescript title="app/tools/put-content.ts"
+import { tool } from "ai";
+import { z } from "zod";
+import { getSession } from "aixyz/app/plugins/session";
+import type { Accepts } from "aixyz/accepts";
+
+export default tool({
+  description: "Store a key-value pair in the current user's session",
+  inputSchema: z.object({
+    key: z.string(),
+    value: z.string().nullable(),
+  }),
+  execute: async ({ key, value }) => {
+    const session = getSession();
+    if (!session) {
+      return { success: false, error: "No authenticated signer in context" };
+    }
+
+    if (value === null) {
+      await session.delete(key);
+      return { success: true, key, deleted: true };
+    }
+
+    await session.set(key, value);
+    return { success: true, key };
+  },
+});
+
+export const accepts: Accepts = { scheme: "exact", price: "$0.01" };
+```
+
+## Skills
+
+| Skill         | Description                                     | Price  |
+| ------------- | ----------------------------------------------- | ------ |
+| `put-content` | Store key-value content in payer-scoped session | $0.01  |
+| `get-content` | Retrieve stored content from session            | $0.001 |
+
+## Running
+
+```bash
+cd examples/x402-sessions
+# create a .env file
+bun install
+bun run dev
+```
+
+<CardGroup cols={2}>
+  <Card title="SessionPlugin API" icon="plug" href="/api-reference/session-plugin">
+    Full API reference for SessionPlugin, Session, and SessionStore.
+  </Card>
+  <Card title="x402 Payments" icon="credit-card" href="/protocols/x402">
+    Payment protocol that provides payer identity for sessions.
+  </Card>
+</CardGroup>

package/docs/templates/basic/with-vercel-blob.mdx

@@ -0,0 +1,61 @@
+---
+title: "Vercel Blob"
+description: "MCP-only template that stores text on Vercel Blob"
+---
+
+<Info>
+  **Source:** [`examples/with-vercel-blob`](https://github.com/AgentlyHQ/aixyz/tree/main/examples/with-vercel-blob)
+</Info>
+
+## Overview
+
+This template exposes two MCP tools, `put-text` and `get-text`, that store and retrieve text using Vercel Blob. Each call is priced at `$0.001` via x402. There is **no** `app/agent.ts` — the server only serves `/mcp`.
+
+## Project Structure
+
+```
+with-vercel-blob/
+├── aixyz.config.ts             # Agent metadata + x402 config
+├── app/
+│   ├── icon.svg                # Template icon
+│   └── tools/
+│       ├── put-text.ts         # Write txt blob
+│       └── get-text.ts         # Read txt blob
+├── package.json
+├── tsconfig.json
+└── vercel.json
+```
+
+## Tools
+
+### `put-text`
+
+- Input: `text` (string, 1–50k chars)
+- Returns: `{ id }` — a UUID identifying the stored text
+
+### `get-text`
+
+- Input: `id` (UUID returned by `put-text`)
+- Returns: `{ id, text }`
+
+## Environment
+
+Set a Vercel Blob read/write token before running locally (required by both tools):
+
+```bash
+echo 'BLOB_READ_WRITE_TOKEN=...' >> .env.local
+```
+
+## Payment
+
+`put-text` and `get-text` each charge `$0.001` per call using the x402 settings in `aixyz.config.ts` (Base mainnet in production, Base Sepolia in development).
+
+## Running locally
+
+```bash
+cd examples/with-vercel-blob
+bun install
+bun run dev
+```
+
+Connect any MCP client (Claude Desktop, VS Code MCP extension, etc.) to `http://localhost:3000/mcp` and call `put-text` / `get-text` with the schemas above.

package/docs/templates/overview.mdx

@@ -29,6 +29,9 @@ Standard agents using `app/agent.ts` + `app/tools/`. No custom server — the se
   <Card title="Chainlink" icon="link" href="/templates/basic/chainlink">
     Chainlink price feeds on Ethereum mainnet.
   </Card>
+  <Card title="Vercel Blob" icon="file-lines" href="/templates/basic/with-vercel-blob">
+    MCP-only txt storage with put-text/get-text using @vercel/blob.
+  </Card>
 </CardGroup>
 
 ## Advanced
@@ -54,4 +57,7 @@ Custom server wiring, bring-your-own payment facilitator, and testing patterns.
   <Card title="Express Integration" icon="plug" href="/templates/advanced/with-express">
     Mount AixyzApp as Express middleware alongside your own routes.
   </Card>
+  <Card title="x402 Sessions" icon="database" href="/templates/advanced/x402-sessions">
+    Payer-scoped session storage with x402 payment identity.
+  </Card>
 </CardGroup>

package/examples/boilerplate/AGENTS.md

@@ -0,0 +1,9 @@
+<!-- BEGIN:aixyz-agent-rules -->
+
+# aixyz: ALWAYS read docs before coding
+
+Before any aixyz work, find and read the relevant doc in `node_modules/aixyz/docs/`.
+And you can read `node_modules/aixyz/examples/` for examples that you can reference.
+Your training data is outdated — the docs are the source of truth.
+
+<!-- END:aixyz-agent-rules -->