@aventara/next 0.0.0-stage → 1.0.0-rc.10

package/CHANGELOG.md

@@ -0,0 +1,108 @@
+# @aventara/next
+
+## 1.0.0-rc.10
+
+### Patch Changes
+
+- 04bb39a: `engines.node` is now `^22.23.4 || >=24.22.1`, the Node security releases of 2026-10-20 (CVE-2026-105481,
+  CVE-2026-105482, CVE-2026-105483, CVE-2026-106069, CVE-2026-106072, CVE-2026-106073, CVE-2026-106074,
+  CVE-2026-111497). The bins refuse an older Node in one sentence naming that range.
+- 587dd01: The route handlers answer `POST {api}/_access/can` when the Framework is built with `access`, through
+  `AvProtocol.bind(framework).handleCan`, with the request's state seeded as on every other protocol route.
+- d7e7369: `avClient.$access`: `framework.serverClient.$access` with the request filled in. `can` is answered under the
+  request's state; `me()` and the other Aventara Access verbs run in process with the headers of `next/headers` (a
+  Server Action's sign-in sets its cookie through Access itself). `ready()` registers the verbs for
+  `@/aventara/universal` on the server.
+- 7ee547b: `avClient.$access` carries Aventara Access's `kiosk` verbs (`switchUser`, `lock`, `setPin`, `enrollDevice`,
+  `revokeDevice`) when the provider states them, run in process with the headers of `next/headers`, so a Server Action's
+  switch sets the rotated device cookie through Access itself; `ready()` registers them for `@/aventara/universal`.
+- 88263a1: Documentation: `$access.can([])` answers `[]`, not a refusal; the MCP README states the query and fragment rule for
+  every authorization server.
+- 15f3402: `avClient.$access` holds only the verbs the access provider offers, as `serverClient.$access` does. Calling another one
+  rejects with `AvProtocolError` `A2002`, naming why (no `access`, or a provider that does not offer that verb), instead
+  of a `TypeError`.
+
+  In `next dev`, an edit that changes only a function (a guard's or a pipe's body, the adapter factory) builds the
+  Framework again; it no longer needs a restart.
+
+- Updated dependencies [587dd01]
+- Updated dependencies [d7e7369]
+- Updated dependencies [7ee547b]
+- Updated dependencies [f52c499]
+- Updated dependencies [2907484]
+- Updated dependencies [a6bbdf0]
+- Updated dependencies [3e26549]
+- Updated dependencies [a6bbdf0]
+- Updated dependencies [6f3f6f6]
+- Updated dependencies [04bb39a]
+- Updated dependencies [d7e7369]
+- Updated dependencies [3fb3333]
+- Updated dependencies [827ccb6]
+- Updated dependencies [7f5abc3]
+- Updated dependencies [88263a1]
+- Updated dependencies [10341d5]
+- Updated dependencies [8129844]
+- Updated dependencies [88263a1]
+- Updated dependencies [3020b5c]
+- Updated dependencies [88263a1]
+- Updated dependencies [88263a1]
+  - @aventara/core@1.0.0-rc.10
+  - @aventara/mcp@1.0.0-rc.10
+
+## 1.0.0-rc.9
+
+### Patch Changes
+
+- 09c5703: New package `@aventara/next`: hosts an Aventara Framework in a Next.js App Router application (Next `>=16.4 <17`,
+  Node runtime). It is in the fixed version group, released at the same version as every other package. `react` (`^19`)
+  is a peer, and `@aventara/mcp` an optional one. The entry is server-only.
+
+  - `Aventara({ ...aventaraConfig, adapter, state })` takes the configuration `createFramework` takes, flat. `adapter`
+    may be a function that builds the adapter (it may return a promise), and `state` (`({ headers, request }) => state`)
+    seeds each request's `ctx.$state`. It returns at once and builds nothing: the Framework is created on first use,
+    once.
+  - It returns `{ handlers, avClient, avApp, ready }`. `handlers` is `{ GET, POST, PUT, PATCH, DELETE }` for one
+    catch-all route file (`src/app/api/[...aventara]/route.ts`), serving the protocol's operation routes,
+    `GET /_contract` and `POST /_transactions`. `avClient` is the client layer for Server Components and Server Actions
+    (`framework.serverClient`, with this request's `state`). `avApp` is the application layer for trusted server code
+    (`framework.application`). `ready()` builds the Framework once and rejects with the construction error, so
+    `src/instrumentation.ts` can await it and a bad configuration fails `next start`.
+  - `Aventara({ framework, state })` hosts a Framework you built with `createFramework`, as
+    `AventaraModule.forRoot({ framework })` does in NestJS. A Framework and a configuration together are a type error,
+    and are refused when `Aventara()` is called.
+  - `access`: an access provider (from `@aventara/core`). Its `policy` checks each request and its `state` seeds
+    `ctx.$state`, called with the same `{ headers, request }`. It does not go with `state` or `policy`.
+  - `aventara-build --client` writes `@/aventara/client` (the browser client) and `@/aventara/universal`, whose `avClient`
+    calls `/api` in the browser and answers the same request in process on the server. `avDehydrate` (this package) and
+    `avHydrate` (`@/aventara/client`) carry `Date`, `bigint`, `Uint8Array` and decimal values from a Server Component to
+    a Client Component, through TanStack Query's `serializeData`/`deserializeData` or an SWR `fallback`.
+  - With `mcp` configured, the same `handlers` serve `@aventara/mcp`'s endpoint and its OAuth protected-resource
+    metadata, each from a one-line route file. On Next.js `mcp` needs `authorization`: without it the configuration is
+    a type error on the `Aventara({...})` call, or refused when the Framework is built. The endpoint is named at the
+    origin the agent called (`X-Forwarded-Host` and `X-Forwarded-Proto` when present, else `Host`).
+  - Every copy of `src/aventara/server.ts` that Next.js evaluates in one server process shares one Framework per `api`
+    path, so `ready()` in `instrumentation.ts` builds the one the routes use. In production, a different configuration
+    on a path already held is refused when `Aventara()` is called; in development it replaces the held one.
+  - `serverExternalPackages: ["@aventara/core", "@aventara/prisma7-adapter"]` in `next.config.ts` is required: Node.js
+    then loads core and the adapter once per server process instead of a copy per layer, so every layer gets values
+    and errors of the same classes and one Prisma client. `aventara new --host next` and `aventara init` add it, or
+    print it when they cannot edit the config safely.
+  - A call reads the database, so it runs at request time: every `avClient`, `avApp` and `@/aventara/universal` call
+    first awaits Next's `io()` (`next/cache`). Under Cache Components (`cacheComponents: true`, create-next-app's
+    default) `next build` never runs one while it prerenders a page, and a page that calls one needs what any uncached
+    database read needs: the calling component inside `<Suspense>` (or a `loading.tsx`), `"use cache"` on a function
+    that makes the call, or `export const instant = false`. Without one, `next build` fails with Next's own message
+    naming the three. In a request, inside `"use cache"`, in a Server Action, in an `after()` callback and without
+    Cache Components the call runs at once.
+  - `AvNextHandlers` (the type of `handlers`), `AvNextClientTransaction` (`avClient.transaction`) and
+    `AvNextAppTransaction` (`avApp.transaction`) are exported, so a project that emits declarations
+    (`declaration: true`) can write `export const { handlers, avClient, avApp, ready } = Aventara(...)` with no
+    annotation. `AvNextStateContext`, what the `state` option is handed (`{ headers, request? }`), is exported too,
+    for a `state` function written in a file of its own.
+
+- Updated dependencies [205a379]
+- Updated dependencies [a0bb05e]
+- Updated dependencies [86ab319]
+- Updated dependencies [fdf52e6]
+  - @aventara/core@1.0.0-rc.9
+  - @aventara/mcp@1.0.0-rc.9

package/LICENSE

@@ -0,0 +1,91 @@
+Required Notice: Copyright 2026 Mohamed Ragheb
+
+# PolyForm Shield License 1.0.0
+
+<https://polyformproject.org/licenses/shield/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncompete
+
+Any purpose is a permitted purpose, except for providing any product that competes with the software or any product the licensor or any of its affiliates provides using the software.
+
+## Competition
+
+Goods and services compete even when they provide functionality through different kinds of interfaces or for different technical platforms.  Applications can compete with services, libraries with plugins, frameworks with development tools, and so on, even if they're written in different programming languages or for different computer architectures.  Goods and services compete even when provided free of charge.  If you market a product as a practical substitute for the software or another product, it definitely competes.
+
+## New Products
+
+If you are using the software to provide a product that does not compete, but the licensor or any of its affiliates brings your product into competition by providing a new version of the software or another product using the software, you may continue using versions of the software available under these terms beforehand to provide your competing product, but not any later versions.
+
+## Discontinued Products
+
+You may begin using the software to compete with a product or service that the licensor or any of its affiliates has stopped providing, unless the licensor includes a plain-text line beginning with `Licensor Line of Business:` with the software that mentions that line of business.  For example:
+
+> Licensor Line of Business: YoyodyneCMS Content Management System (http://example.com/cms)
+
+## Sales of Business
+
+If the licensor or any of its affiliates sells a line of business developing the software or using the software to provide a product, the buyer can also enforce [Noncompete](#noncompete) for that product.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+A **product** can be a good or service, or a combination of them.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all its affiliates.
+
+**Affiliates** means the other organizations than an organization has control over, is under the control of, or is under common control with.
+
+**Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/LICENSE-ADDITIONAL-PERMISSION.md

@@ -0,0 +1,9 @@
+# Additional Permission — Aventara
+
+Copyright 2026 Mohamed Ragheb
+
+In addition to the permissions of the PolyForm Shield License 1.0.0 in `LICENSE`, the licensor grants the following additional permission:
+
+The Noncompete section applies only to providing a product that competes with the software itself — the Aventara framework, its packages and its tooling. Providing a product that competes with any other product the licensor or its affiliates provide using the software is a permitted purpose.
+
+This additional permission only adds to your permissions; it does not restrict or replace any term of `LICENSE`.

package/README.md

@@ -1,3 +1,323 @@
-# Temporary Holding Version
+# `@aventara/next`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Hosts an Aventara Framework in a Next.js App Router application (Next 16.4 or later 16.x, Node runtime). It serves the
+framework's HTTP protocol (`AvProtocol.bind(framework)` from `@aventara/core/protocol`) from one catch-all route file.
+Every rule of the protocol (routes, decoding, statuses, envelopes, headers, absence) is core's; this package only turns
+a Web `Request` into the protocol's request and writes the protocol's answer back as a Web `Response`.
+
+`@aventara/core` is its dependency; `next` (`>=16.4 <17`) and `react` (`^19`) are peers, and `@aventara/mcp` an
+optional one (see MCP). The entry is server-only: a Client Component
+importing it fails the Next.js build.
+
+## Setup
+
+```ts
+// src/aventara/server.ts
+import "server-only";
+import { Aventara } from "@aventara/next";
+import { createPrismaAdapter } from "@aventara/prisma7-adapter";
+import { prisma } from "../prisma";
+import adapter from "./adapter";
+import { aventaraConfig } from "./config";
+
+export const { handlers, avClient, avApp, ready } = Aventara({
+  ...aventaraConfig, // api: "/api", resources, policy, ...
+  adapter: () => createPrismaAdapter({ ...adapter, client: prisma }),
+  state: async ({ headers }) => ({ user: await userFrom(headers) }), // your auth library
+});
+```
+
+```ts
+// src/app/api/[...aventara]/route.ts (the folder matches api: "/api")
+import { handlers } from "@/aventara/server";
+
+export const { GET, POST, PUT, PATCH, DELETE } = handlers;
+```
+
+| Option | What it is |
+|---|---|
+| everything `createFramework` takes | `api`, `resources`, `policy`, `limits`, `prebuilt`, ... checked exactly as `createFramework` checks them |
+| `adapter` | the adapter, or a function that builds it (it may return a promise), called on the first request |
+| `state` | `({ headers, request }) => state`: seeds each request's `ctx.$state` (where `policy.principal` reads the user) |
+| `access` | an access provider (see `@aventara/core`): its `policy` checks each request and its `state` seeds `ctx.$state`, handed the same `{ headers, request }`. Not together with `state` or `policy` |
+
+Or hand it a Framework you built, as `createFramework` resolved it (as `AventaraModule.forRoot({ framework })` takes
+one in NestJS), with `state` beside it (or none, when it was built with `access`):
+
+```ts
+const framework = await createFramework({ ...aventaraConfig, adapter: createPrismaAdapter({ ...adapter, client }) });
+export const { handlers, avClient, avApp, ready } = Aventara({ framework, state });
+```
+
+Every member works on that Framework, which is never built again: `avClient.tx` and `avApp.appTx` build handles at
+once, and `ready()` checks it (a Resource named like a member, `mcp` without `authorization`) and registers the
+universal path. A Framework and a configuration are two sources of one Framework, so the options carry one or the
+other: a configuration key beside `framework` is a type error, and `Aventara()` refuses it when called, naming the
+keys. So is a `framework` that is not one.
+
+`Aventara()` returns at once and builds nothing: `next build` imports the route module, so the Framework (and the
+adapter, when it is a function) is created on first use, or by `ready()`, once. A configuration `createFramework`
+refuses rejects that use with its `AvConstructionError`.
+
+| Member | What it is |
+|---|---|
+| `handlers` | `{ GET, POST, PUT, PATCH, DELETE }` for the catch-all route file |
+| `avClient` | the client layer for Server Components and Server Actions: `framework.serverClient`, with this request's `state`; `avClient.tx` and `avClient.transaction([...])` |
+| `avApp` | the application layer for trusted server code: `framework.application`; `avApp.appTx` and `avApp.transaction([...])` |
+| `ready` | `() => Promise<void>`: builds the Framework once; rejects with the construction error; registers the in-process path `@/aventara/universal` calls on the server |
+
+`handlers` is typed `AvNextHandlers`, and `avClient.transaction` and `avApp.transaction` `AvNextClientTransaction` and
+`AvNextAppTransaction`, all three exported, so a project that emits declarations (`declaration: true`) writes
+`export const { handlers, avClient, avApp, ready } = Aventara(...)` with no annotation. `AvNextStateContext` is what
+`state` is handed (`{ headers, request? }`), for a `state` function written in a file of its own:
+`export const state = async ({ headers }: AvNextStateContext) => ({ user: await userOf(headers) });`.
+
+## Server Components and Server Actions
+
+```tsx
+// src/app/campaigns/page.tsx
+import { Suspense } from "react";
+import { avClient } from "@/aventara/server";
+
+async function Campaigns() {
+  const campaigns = await avClient.Campaign.find.many({
+    where: { startsAt: { gt: new Date() } },
+    select: ["id", "name", "startsAt"],
+  });
+  return <ul>{campaigns.map((c) => <li key={c.id}>{c.name}</li>)}</ul>;
+}
+
+export default function Page() {
+  return (
+    <Suspense fallback={<p>Loading…</p>}>
+      <Campaigns />
+    </Suspense>
+  );
+}
+```
+
+`avClient.<Resource>.<family>.<variant>(args, options?)` is `framework.serverClient`: typed from the Client
+Contract's view (what the client layer hides is absent), taking and answering application values (`Date`, `bigint`,
+`AvDecimal`, `Uint8Array`). A call runs in process, with no HTTP: the same client pipelines, validation, exposure and
+policy as a request to `handlers`, with the principal `policy.principal` reads from `state`. A refusal is thrown as
+its `AvError` class (`AvAuthError` for the policy).
+
+`state` is called with `{ headers }` from `next/headers` (there is no `request` outside a route call), once per
+server render however many calls the render makes. Outside a render, in a Server Action's body for example, it runs
+once per call. A call that names its own `state` in its options uses it as given. Without a `state` option, calls
+start from `{}` and read no headers.
+
+### Request-time data
+
+A call reads the database, so Next.js renders it at request time, never into the page `next build` prerenders. Every
+`avClient`, `avApp` and `@/aventara/universal` call first awaits Next's `io()` (`next/cache`). Under Cache Components
+(`cacheComponents: true`, which create-next-app sets), a page that calls one needs what any uncached database read
+needs, one of:
+
+- `<Suspense>` around the component that calls it (or a `loading.tsx` beside the page): the fallback is prerendered and
+  the data streams in at request time, as above;
+- `"use cache"` on a function that makes the call: the result is cached, and prerendered with the page;
+- `export const instant = false` in the page: it renders whole, at request time.
+
+With none of them, `next build` fails with Next's own message, which names the three. In a request, inside
+`"use cache"`, in a Server Action, in an `after()` callback and without Cache Components the call runs at once.
+
+With `access`, `avClient.$access` is `framework.serverClient.$access` with this request filled in: `can([...])` is
+answered under the request's state, and `me()`, `signIn(...)` and the other verbs the provider offers run Aventara
+Access in process with the headers of `next/headers`. In a Server Action, Access sets a sign-in's cookie itself
+(Better Auth's `nextCookies`). `@/aventara/universal`'s `$access` does the same on the server, through what `ready()`
+registers, and calls Access's own routes in the browser. `$access` holds the verbs the provider offers, read from the
+options before the Framework is built, as `serverClient.$access` holds them. Calling another one rejects with
+`AvProtocolError` `A2002`, naming why: no `access`, or a provider whose `client` does not offer that verb.
+
+On Access's `kiosk` profile, call `switchUser`, `lock` and `enrollDevice` from a Server Action (or from the browser),
+never while rendering a Server Component: each rotates the device's credential cookie, which Next lets Access set only
+in a Server Action or a Route Handler, so a rotation during a render is lost and the device's next switch is refused. Never call a verb that
+changes anything (`signIn`, `signUp`, `signOut`, `resetPassword`, and the kiosk's five) inside `"use cache"`: a cached
+result would replay one caller's answer to another and skip the call. Each verb's answer is projected onto its result
+schema on the server too, so no session token or device secret reaches your code.
+
+`avApp` is `framework.application`: trusted server code. It reads no request, and the policy checks a call only when
+it names a principal (`{ as: principal }`).
+
+Transactions keep their layer: `avClient.tx` builds client-layer handles (`framework.serverClientTx`) and
+`avClient.transaction([...])` runs them with this request's state; `avApp.appTx` builds application handles (and
+`avApp.appTx.$sql`), and `avApp.transaction([...])` runs them. A list that mixes the two is a type error, and refused
+at runtime (`A2004`). Handles are built on the built Framework: `await ready()` before building them.
+
+## Startup
+
+```ts
+// src/instrumentation.ts
+export async function register() {
+  if (process.env.NEXT_RUNTIME === "nodejs") {
+    const { ready } = await import("@/aventara/server");
+    await ready();
+  }
+}
+```
+
+`ready()` builds the Framework and its routes, once: a second call returns the same promise. It rejects with the
+construction error, so a bad configuration fails `next start`. It reads no request, so it runs where there is none
+(`instrumentation.ts`, a script).
+
+### `serverExternalPackages` (required)
+
+```ts
+// next.config.ts
+const nextConfig: NextConfig = {
+  serverExternalPackages: ["@aventara/core", "@aventara/prisma7-adapter"],
+};
+```
+
+Next.js bundles a package into each layer of the server (instrumentation, route handlers, Server Components) as a
+copy of its own. Listed here, `@aventara/core` and the adapter are loaded by Node.js once per server process instead:
+one core, so the Framework every layer shares (below) answers each layer with values and errors of the same classes
+(`AvDecimal`, `AvValidationError`, ...), and one Prisma client. `aventara new --host next` and `aventara init` add the
+line (an existing config they cannot edit safely gets it printed instead). `@aventara/next` itself stays bundled: it
+relies on Next.js's server aliases (`next/navigation`, `next/headers`, `server-only`).
+
+Next.js evaluates `src/aventara/server.ts` more than once in one server process (once for `instrumentation.ts`, again
+for the routes and pages). Every copy that calls `Aventara()` with the same options shares one Framework, held per
+`api` path for the process, so `ready()` in `instrumentation.ts` builds the one the routes use, with one adapter, and
+`avClient.tx` works from the first request. Two instances on two `api` paths hold two. In production, a different
+configuration on a path already held is refused when `Aventara()` is called; in development it replaces the held one,
+as `next dev` evaluates the file again after an edit. Copies are told apart by the options' data (Next.js rewrites a
+function's source in each layer). An edit that changes only a function, a guard's or a pipe's body or the adapter
+factory, is told by each layer from the text that layer saw last: in development the first layer to see it builds the
+Framework again, and the other layers join that build. A Framework given as `{ framework }` is that call's own.
+
+Once the Framework is built, `ready()` also registers the path `@/aventara/universal`'s `avClient` takes on the server
+(below). Without `instrumentation.ts`, that `avClient` refuses its calls on the server in one sentence.
+
+## Prefetch and hydrate: `@/aventara/universal`, `avDehydrate`, `avHydrate`
+
+`aventara-build --client` writes `src/aventara/universal.ts`. Its `avClient` has the browser client's types and runs on
+both sides: in the browser it calls `/api`; on the server it answers the same request in process, through the bound
+protocol and with this request's `state`, so a query prefetched in a Server Component and refetched in the browser
+gets the same values (`Date`, `bigint`, the client's own `AvDecimal`).
+
+A decimal is a class instance, which React refuses to pass from a Server Component to a Client Component. `avDehydrate`
+(this package, server side) turns each `Date`, `bigint`, `Uint8Array` and decimal into a tagged plain object, and
+`avHydrate` (`@/aventara/client`, browser side) turns them back.
+
+```ts
+// src/app/notes/notes.queries.ts (server and browser)
+import { queryOptions } from "@tanstack/react-query";
+import { avClient } from "@/aventara/universal";
+
+export const notesQuery = queryOptions({
+  queryKey: ["notes"],
+  queryFn: () => avClient.Note.find.many({ select: ["id", "title", "createdAt"] }),
+});
+```
+
+```tsx
+// src/app/notes/page.tsx (Server Component)
+import { dehydrate, HydrationBoundary, QueryClient } from "@tanstack/react-query";
+import { Suspense } from "react";
+import { avDehydrate } from "@aventara/next";
+import { notesQuery } from "./notes.queries";
+import { NoteList } from "./note-list";
+
+async function Notes() {
+  const queryClient = new QueryClient();
+  await queryClient.prefetchQuery(notesQuery);
+  return (
+    <HydrationBoundary state={dehydrate(queryClient, { serializeData: avDehydrate })}>
+      <NoteList />
+    </HydrationBoundary>
+  );
+}
+
+export default function Page() {
+  return (
+    <Suspense fallback={<p>Loading…</p>}>
+      <Notes />
+    </Suspense>
+  );
+}
+```
+
+```tsx
+// src/app/providers.tsx
+"use client";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { avHydrate } from "@/aventara/client";
+
+const queryClient = new QueryClient({ defaultOptions: { hydrate: { deserializeData: avHydrate } } });
+export const Providers = ({ children }: { children: React.ReactNode }) => (
+  <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+);
+```
+
+With SWR, pass `avDehydrate({ [key]: data })` from the Server Component and `avHydrate(fallback)` to `SWRConfig`'s
+`fallback` in the Client Component.
+
+Importing `@/aventara/client` instead of `@/aventara/universal` in shared code opts out of running on the server: its
+calls are refused there.
+
+## Routes
+
+`handlers` answers the protocol's routes under `api`: each operation route (`POST /api/_resources/...`),
+`GET /api/_contract` (with its `ETag`, and `304` on `If-None-Match`) and `POST /api/_transactions` when the
+ClientContract's transactions are interactive. Every method is exported so that a wrong method on an operation route
+gets the protocol's `405` (`A2012`) with `Allow`. A path the protocol does not own goes to Next's `notFound()`.
+
+A request body is read up to `limits.maxRequestBytes` decoded bytes; `gzip`, `deflate` and `br` bodies are inflated,
+and any other content coding is the protocol's `415` (`A2011`).
+
+## MCP
+
+With `mcp` in the configuration, the same `handlers` also serve `@aventara/mcp`'s endpoint and its OAuth
+protected-resource metadata. Add one route file for each path:
+
+```ts
+// src/aventara/server.ts
+export const { handlers } = Aventara({
+  ...aventaraConfig,
+  mcp: {
+    path: "/mcp",
+    authorization: {
+      servers: ["https://auth.example.com"],
+      verify: async (token) => (await verifyAccessToken(token)) ?? null, // your token check
+    },
+  },
+  adapter: () => createPrismaAdapter({ ...adapter, client: prisma }),
+});
+```
+
+```ts
+// src/app/mcp/route.ts
+import { handlers } from "@/aventara/server";
+
+export const { GET, POST, DELETE } = handlers;
+```
+
+```ts
+// src/app/.well-known/oauth-protected-resource/mcp/route.ts
+import { handlers } from "@/aventara/server";
+
+export const { GET } = handlers;
+```
+
+Install `@aventara/mcp` at the same version as `@aventara/core` (`npm install --save-exact @aventara/mcp@<version>`).
+It is an optional peer, loaded only when `mcp` is configured; when it is missing, the first request fails with a
+sentence that names the install command.
+
+On Next.js, `mcp` needs `authorization`. Without it, `@aventara/mcp` answers only callers on the same machine that
+send no `x-forwarded-for`, and Next.js adds `x-forwarded-for` to every request, so every caller would be refused. An
+`mcp` without `authorization` is a type error on the `Aventara({...})` call, and, for a configuration typed wider than its literal, refused when the Framework is built (the first request), with a sentence that says so.
+
+Everything the endpoint answers is `@aventara/mcp`'s: the bearer check and its `401` with `WWW-Authenticate`, the
+tools, the tool calls (each one an agent-origin protocol request, with `state` and the token's claims in
+`ctx.$state.mcp.claims`), the `405` on `GET` and `DELETE` (the endpoint is stateless) and the metadata document. The
+request body is read up to the Agent Contract's `maxRequestBytes` and handed on as sent.
+
+## Status
+
+A prerelease, installed with its tag:
+
+```bash
+npm install @aventara/next@rc
+```