@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/docs/src/content/docs/packages/core.mdx

@@ -0,0 +1,186 @@
+---
+title: "@ic-reactor/core"
+description: "What @ic-reactor/core and @ic-reactor/core/testing export, their peers, and how to install them"
+---
+
+`@ic-reactor/core` is the client of ic-reactor 4. It sits on a module that
+`meant gen` writes from a `.did` file, and it has no React in it. It
+gives you:
+
+- a client with query keys that carry the caller, TanStack Query options for
+  reads and writes, and network resolution;
+- one error type that says whether a call may have executed;
+- strict helpers for token amounts;
+- a test client over an in-memory replica, in a separate entry.
+
+It works in a browser, in Node and on a server. It ships as ES modules only,
+with no CommonJS build: use it from a package with `"type": "module"` or through a
+bundler (see
+[ES modules only](/v4/guides/getting-started/#es-modules-only)). For React, add
+[`@ic-reactor/react`](/v4/packages/react/). For Vite, add
+[`@ic-reactor/vite-plugin`](/v4/packages/vite-plugin/).
+
+## Install
+
+```sh
+npm install @ic-reactor/core @icp-sdk/core @tanstack/query-core
+npm install --save-exact @meantjs/schema@0.6.0
+npm install @icp-sdk/auth   # for Internet Identity
+```
+
+The generator is a separate dev dependency, pinned to the version that pairs
+with `@meantjs/schema`:
+
+```sh
+npm install --save-dev --save-exact @meantjs/cli@0.5.1
+```
+
+See [Getting started](/v4/guides/getting-started/) for the first read and write.
+
+Node `>=22.12.0`, the first Node 22 that loads an ES module with `require()`
+(22.12 itself prints an experimental warning when it does).
+
+## Peers
+
+| Peer                   | Range                                                                                                      |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `@meantjs/schema`      | exactly `0.6.0`: the module `meant gen` writes imports it                                                  |
+| `@icp-sdk/core`        | `^6.1.0`                                                                                                   |
+| `@tanstack/query-core` | `^5.62.0`                                                                                                  |
+| `@noble/curves`        | `^2.2.0`, optional: only `@ic-reactor/core/testing` signs with it, and `@icp-sdk/core` installs it already |
+
+With React, install `@tanstack/query-core` at the exact version your
+`@tanstack/react-query` depends on, and check that
+`npm ls @tanstack/query-core` shows one copy; see
+[the React package](/v4/packages/react/#one-copy-of-tanstackquery-core).
+
+`@icp-sdk/auth` is not a peer. Install it when users sign in with Internet
+Identity: its `AuthClient` is an `AuthLike` as it is, see
+[Auth](/v4/guides/auth/).
+
+## Exports of `@ic-reactor/core`
+
+The entry has 13 names: four at runtime and nine types. The export budget caps
+it at 13.
+
+| Export             | Kind    | What it is                                                                                                                                                                                                                    |
+| ------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `createClient`     | runtime | Builds a client from a network and a caller. See [The client](/v4/guides/client/).                                                                                                                                            |
+| `isReactorError`   | runtime | Tests whether a thrown value is a `ReactorError`; with a canister and a method, one of that call's, its `err` typed. See [Errors](/v4/guides/errors/).                                                                        |
+| `parseUnits`       | runtime | Text to base units: `parseUnits("1.5", 8)` is `150000000n`. See [Values and units](/v4/guides/values/).                                                                                                                       |
+| `formatUnits`      | runtime | Base units to text, without losing digits. See [Values and units](/v4/guides/values/).                                                                                                                                        |
+| `Client`           | type    | A client offers: `canister`, `canisterId`, `queryOptions`, `mutationOptions`, `resendOf`, `queryKey`, `encode`, `func`, `time`, `signIn`, `signOut`, `caller`, `authState`, `subscribe`, `queryClient`, `network`, `dispose`. |
+| `ClientOptions`    | type    | The argument of `createClient`: a `network`, and exactly one of `identity` and `auth`.                                                                                                                                        |
+| `Network`          | type    | `"ic"`, `"local"`, `"env"`, or `{ host, rootKey?, name?, fetchRootKey? }`.                                                                                                                                                    |
+| `AuthLike`         | type    | What `auth` must be: the shape of an `@icp-sdk/auth` 10 `AuthClient`. See [Auth](/v4/guides/auth/).                                                                                                                           |
+| `AuthState`        | type    | `{ status, principal, expiresAt? }`: who calls now, why, and until when.                                                                                                                                                      |
+| `Canister`         | type    | What `client.canister<Actor>(actor, target)` returns: one async method per Candid method.                                                                                                                                     |
+| `CanisterTarget`   | type    | `{ id }` or `{ name }`, each with an optional `certified`. See [Reads](/v4/guides/reads/#certified-reads).                                                                                                                    |
+| `ReactorError`     | type    | The error every call rejects with. A type only: there is no class, so test with `isReactorError`.                                                                                                                             |
+| `ReactorErrorKind` | type    | The eight kinds of a `ReactorError`.                                                                                                                                                                                          |
+
+The signatures that matter most:
+
+```ts nocheck
+function createClient(options: ClientOptions): Client
+
+type ClientOptions = {
+  readonly network: Network
+  readonly allowEnvConfig?: boolean
+  readonly fetch?: typeof globalThis.fetch
+  readonly maxDepth?: number
+  readonly maxElements?: number
+} & (
+  | { readonly identity: Identity | "anonymous"; readonly auth?: never }
+  | {
+      readonly auth: (network: AuthNetwork) => AuthLike
+      readonly identity?: never
+    }
+)
+
+// Not exported: what the auth factory is handed, `network` in `(network) => new AuthClient(network)`.
+type AuthNetwork = {
+  readonly agentOptions: {
+    readonly host: string
+    readonly rootKey?: Uint8Array
+    readonly shouldFetchRootKey: boolean
+    readonly fetch?: typeof globalThis.fetch
+  }
+  readonly identityProvider?: {
+    readonly authorizeUrl: string
+    readonly canisterId: string
+  }
+}
+
+function isReactorError(error: unknown): error is ReactorError<unknown>
+function isReactorError<A, M extends keyof A & string>(
+  error: unknown,
+  canister: Canister<A>,
+  method: M
+): error is ReactorError<ErrorOf<A, M>> & { readonly method: M } // ErrorOf: the method's Err arm, or never
+
+function parseUnits(
+  text: string,
+  decimals: number,
+  options?: { signed?: boolean }
+): bigint
+function formatUnits(
+  value: bigint,
+  decimals: number,
+  options?: { maxFractionDigits?: number; minFractionDigits?: number }
+): string
+```
+
+`createClient` does no work until it is used, so the same line runs in a
+server render and in a browser. It throws a `TypeError` for options that do not
+say who calls, say it twice, or name a network, `maxDepth` or `maxElements` it cannot use; for
+an option it does not have, in the options or in a network object; and for an
+`allowEnvConfig` or `fetchRootKey` that is not a boolean, a `rootKey` that is
+not 133 bytes in a `Uint8Array`, or a `fetch` that is not a function.
+`parseUnits` and `formatUnits` refuse an option they do not have too.
+The `auth` factory is handed the client's network:
+[Auth](/v4/guides/auth/) says where its `identityProvider` comes from.
+
+## Exports of `@ic-reactor/core/testing`
+
+A separate entry with two names. The main entry never imports it, so none of it
+reaches an app bundle.
+
+| Export             | Kind    | What it is                                                                                    |
+| ------------------ | ------- | --------------------------------------------------------------------------------------------- |
+| `createTestClient` | runtime | A real client over an in-memory replica, with mocked canisters and a sign-in a test controls. |
+| `TestHandlers`     | type    | The handlers of a mocked canister, typed from the generated `Actor`.                          |
+
+See [Testing](/v4/guides/testing/).
+
+## What it does not export
+
+The package exports exactly these names, from exactly two subpaths: `.` and
+`./testing` (and `./package.json`). Every name has one import path, so it does
+not re-export what lives elsewhere:
+
+- `principal`, `isPrincipal` and the `Principal` type come from
+  `@meantjs/schema`.
+- `skipToken`, `useQuery`, `useMutation`, `useSuspenseQuery`,
+  `useInfiniteQuery`, `dehydrate` and `HydrationBoundary` come from TanStack
+  Query (`@tanstack/react-query`, or `@tanstack/query-core` outside React).
+
+## The guide ships in the package
+
+The tarball carries a guide for people and coding agents, written against this
+version: `node_modules/@ic-reactor/core/llms.txt`. It covers setup, values,
+reads, writes, errors and a complete React example. These pages go into more
+depth and agree with it.
+
+## Where to read next
+
+- [Getting started](/v4/guides/getting-started/): install, generate the module, first read and write.
+- [The client](/v4/guides/client/): networks, who calls, canisters, `dispose`.
+- [Values and units](/v4/guides/values/): the value shapes, `parseUnits` and `formatUnits`.
+- [Reads](/v4/guides/reads/) and [Writes](/v4/guides/writes/): the options builders, keys, invalidation and re-sends.
+- [Errors and mayHaveExecuted](/v4/guides/errors/): kinds, codes and what to do for each.
+- [Auth](/v4/guides/auth/): `AuthLike`, Internet Identity and caller changes.
+- [SSR and hydration](/v4/guides/ssr/): one client per request, dehydrate and hydrate.
+- [Testing](/v4/guides/testing/): the test client.
+
+Coming from 3.x? See [Migrating from 3.x](/v4/migrating-from-3/).

package/docs/src/content/docs/packages/mcp.mdx

@@ -0,0 +1,163 @@
+---
+title: "@ic-reactor/mcp"
+description: "An MCP server that gives an AI agent any canister's methods as tools: queries run at once, and an update is sent only after you approve the exact call"
+---
+
+`@ic-reactor/mcp` is an [MCP](https://modelcontextprotocol.io) server that
+gives an AI agent any Internet Computer canister's methods as tools. Name a
+canister, and Claude Code, Cursor or any other MCP client gets one tool per
+method, with an input schema built from the canister's Candid. Queries run at
+once. An update is sent only after you approve that exact call in the client.
+
+The canister's interface is read from its certified `candid:service` metadata
+and compiled with `@meantjs/cli`, the arguments and replies are checked and
+encoded by `@meantjs/schema`, and calls go through an
+[`@ic-reactor/core`](/v4/packages/core/) client, which verifies every
+certificate and says whether a failed write may have run.
+
+## Install
+
+```sh
+npm install --global @ic-reactor/mcp
+```
+
+It installs one command, `ic-reactor-mcp`, and has nothing to import. A global
+install keeps the version you installed until you update it.
+
+Node `>=22.12.0`, as core and react.
+
+## Add it to a client
+
+Claude Code, for the ICP ledger:
+
+```sh
+claude mcp add icp -- ic-reactor-mcp --canister ledger=ryjl3-tyaaa-aaaaa-aaaba-cai
+```
+
+Cursor (`.cursor/mcp.json`) and other clients that take a JSON entry:
+
+```json
+{
+  "mcpServers": {
+    "icp": {
+      "command": "ic-reactor-mcp",
+      "args": ["--canister", "ledger=ryjl3-tyaaa-aaaaa-aaaba-cai"]
+    }
+  }
+}
+```
+
+Without `--identity` the server calls as the anonymous principal: every query
+works and no update is sent. To send updates, give it a key (see
+[A key](#a-key)).
+
+## Tools
+
+| Tool              | What it does                                                                                                                          |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `whoami`          | The principal calls are signed as, the network, whether the client can show the approval form, the listed canisters                   |
+| `list_methods`    | A canister's methods and their Candid signatures, where the interface came from, and whether updates can be sent                      |
+| `describe_method` | One method's Candid (the method and every type it uses), its doc comment, and the JSON Schema of its arguments                        |
+| `query`           | Runs a query method of any canister; `certified: true` makes it a replicated call, as the anonymous principal, with a certified reply |
+| `call`            | Sends an update to a listed canister once you approve it; a query method is run as a query                                            |
+| `<name>_<method>` | One per method of each `--canister`, such as `ledger_icrc1_transfer`, with the method's own input schema                              |
+
+`call` and the update tools are listed only when an update can be sent: the
+server has a key, the client can show a form, and a canister is listed.
+
+Tool arguments and replies are JSON. A `nat`, `int`, `nat64` or `int64` is a
+decimal string such as `"150000000"`, a `blob` is lower-case hex, an `opt` is
+`null` or the value, and a variant is `{ "tag": "Name", "value": payload }`.
+The [package's README](https://github.com/B3Pay/ic-reactor/tree/main/packages/mcp#arguments-and-replies)
+has every Candid type's JSON form.
+
+## Updates and approval
+
+An update (or a oneway call) is sent only when all of these hold, and a
+refusal says which one did not:
+
+1. The server has a key: `--identity <pem file>`.
+2. The canister is listed with `--canister`. Queries reach any canister,
+   updates only the ones you named.
+3. Its interface is certified metadata, or a `.did` you gave with `--did`.
+   An interface read through the uncertified `__get_candid_interface_tmp_hack`
+   query is used for reads only: it is one replica's unproven answer.
+4. The client can show a form (MCP form elicitation), and you tick
+   "Send this call" and accept.
+
+The form shows the canister, the method, the principal that signs, the
+network, the arguments as Candid text (with invisible and bidirectional
+characters escaped), the size and sha256 of the encoded arguments, and where
+the interface came from. Arguments over 20,000 characters of Candid, or a
+method name over 200 characters, are refused, never cut. The server confirms
+the canister's module hash before it asks you and again after you approve, and
+sends nothing if the canister was upgraded in between. Declining, closing the
+form, ten minutes without an answer, or a client error all mean nothing is
+sent. One approval is asked at a time.
+
+A certified read (`query` with `certified: true`) is a replicated call, which
+the IC runs as whatever the canister's module exports under that name. So it
+is made as the anonymous principal, never with your key, and its reply is read
+with the interface of the module installed now.
+
+Claude Code shows the form in a dialog. `claude -p` cancels every form unless
+an `Elicitation` hook answers it, so a headless run sends no update unless you
+wrote a hook that approves.
+
+## A key
+
+`--identity <file>` takes an Ed25519 or secp256k1 private key in PEM form, such
+as `icp identity export <name>` or `dfx identity export <name>` prints. The
+file must be readable by its owner only (`chmod 600`); the server refuses one
+that other users can read. The server never makes a key. Give the agent a key
+of its own, holding only what you would let it spend.
+
+## Options
+
+```text
+--canister <name>=<id>     A canister that gets typed tools and takes updates,
+                           such as ledger=ryjl3-tyaaa-aaaaa-aaaba-cai. A bare
+                           <id> is named after its first five characters.
+--did <name or id>=<path>  Read that canister's interface from this .did file
+                           instead of the network.
+--identity <pem file>      Sign calls with this key (chmod 600).
+--network <ic|local|url>   ic (mainnet, the default), local
+                           (http://127.0.0.1:8000), or a replica's URL.
+--root-key <hex>           The root key (DER, hex) of a --network <url> that
+                           is not on this machine.
+```
+
+A root key is fetched only from a replica on this machine. Mainnet's key is
+built into the agent, and a remote replica's must be given with `--root-key`.
+
+## Limits
+
+- A `.did` over 256 KiB, a service with more than 1,000 methods, or a compile
+  over 2 seconds is refused; the compiler runs in a worker thread.
+- A tool's input schema is cut at about 64,000 characters, names and
+  descriptions included, and says it was cut. The typed tools of one
+  `tools/list` stop at 1,000,000 characters; `query` and `call` still reach a
+  method past that.
+- A tool result is cut at 60,000 characters, with a note that it was cut.
+- A read waits 60 seconds for its answer, and an approved update 6 minutes; an
+  update that gets no answer in time may still have run, and its result says
+  so.
+
+## What the agent sees
+
+Names in a canister's interface (methods, fields, types) are the canister's
+own text and reach the model in tool names, descriptions and schemas. A
+method's doc comment, which is free text, appears only in `describe_method`'s
+result, labelled as written by the canister's authors, and never in a tool
+description. The form is the safeguard for writes: an agent misled by such
+text can still only propose a call, and you read the call itself before it is
+sent.
+
+## Read next
+
+- [Give an agent a canister's tools](/v4/build/agent-tools/): a ledger's tools
+  written by hand with `@ic-reactor/core`, with amounts as decimal text and a
+  transfer that never pays twice.
+- [Errors and mayHaveExecuted](/v4/guides/errors/): what a failed write tells
+  you about whether it ran.
+- [@ic-reactor/core](/v4/packages/core/): the client the server calls through.

package/docs/src/content/docs/packages/react.mdx

@@ -0,0 +1,207 @@
+---
+title: "@ic-reactor/react"
+description: "What @ic-reactor/react exports, its peers, and how to install it"
+---
+
+`@ic-reactor/react` is the React binding of ic-reactor 4: three
+`"use client"` exports over a client made by
+[`@ic-reactor/core`](/v4/packages/core/). There is no hook that wraps
+`useQuery` or `useMutation`. You read and write canisters with TanStack Query's
+own hooks and the options the client builds, `client.queryOptions(...)` and
+`client.mutationOptions(...)`.
+
+The package never re-exports `@ic-reactor/core`, so every name has one import
+path.
+
+Like core, it ships as ES modules only (see
+[ES modules only](/v4/guides/getting-started/#es-modules-only)).
+
+## Install
+
+```sh
+npm install @ic-reactor/core @ic-reactor/react @tanstack/react-query
+npm install @icp-sdk/core @tanstack/query-core
+npm install --save-exact @meantjs/schema@0.6.0
+npm install @icp-sdk/auth   # for Internet Identity
+```
+
+The second and third lines are peers of `@ic-reactor/core`;
+see its [package page](/v4/packages/core/). For a Vite app, see also
+[the Vite plugin](/v4/packages/vite-plugin/).
+
+Peers of this package:
+
+| Peer                    | Range                                                         |
+| ----------------------- | ------------------------------------------------------------- |
+| `@ic-reactor/core`      | exactly this package's version: the two are released together |
+| `@tanstack/react-query` | `^5.90.2`                                                     |
+| `react`                 | `>=18.0.0`                                                    |
+
+Node `>=22.12.0`, the first Node 22 that loads an ES module with `require()`
+(22.12 itself prints an experimental warning when it does).
+
+### One copy of `@tanstack/query-core`
+
+Install `@tanstack/query-core` at the exact version your
+`@tanstack/react-query` depends on (`npm view @tanstack/react-query@<version>
+dependencies`), and check that `npm ls @tanstack/query-core` shows one copy.
+npm installs a second copy when the two differ: core then builds its
+`QueryClient` from one copy and the hooks read the other, each with its own
+`skipToken`. `client.queryOptions()` throws a `TypeError` for the hooks'
+`skipToken`, and in development `ReactorProvider` throws when it is handed
+such a client. Both errors name this fix.
+
+## Exports
+
+The entry has four names. The export budget allows five.
+
+| Export                 | What it is                                                               |
+| ---------------------- | ------------------------------------------------------------------------ |
+| `ReactorProvider`      | Gives a tree one client, and TanStack Query that client's `QueryClient`. |
+| `useClient`            | The client of the nearest provider, for the caller this render shows.    |
+| `useAuth`              | Who calls (`status`, `principal`), with `signIn` and `signOut`.          |
+| `ReactorProviderProps` | A type: `{ client: () => Client; children: ReactNode }`.                 |
+
+Nothing else is importable: the only subpaths are `.` and `./package.json`.
+`useQuery`, `useMutation`, `useSuspenseQuery`, `skipToken`, `dehydrate` and
+`HydrationBoundary` come from `@tanstack/react-query`, and `principal` from
+`@meantjs/schema`.
+
+### ReactorProvider
+
+```ts nocheck
+interface ReactorProviderProps {
+  readonly client: () => Client
+  readonly children: ReactNode
+}
+```
+
+`ReactorProvider` takes a factory, not a client, and calls it once for each
+mounted provider. It renders TanStack's `QueryClientProvider` with
+`client.queryClient`. When it unmounts, it disposes the client only if that
+factory call created it:
+
+- **The provider owns the client.** A factory that creates it,
+  `client={() => createClient({ ... })}`, gives each mounted provider a client
+  of its own, and the provider disposes it when it unmounts. Use this in an app
+  that renders on a server: the factory runs once per request.
+- **The app owns the client.** A client created at module scope, one per tab
+  and used outside React too, is handed over as `client={() => client}`. The
+  provider borrows it and never disposes it.
+
+```tsx
+"use client"
+
+import { createClient } from "@ic-reactor/core"
+import { ReactorProvider } from "@ic-reactor/react"
+import { AuthClient } from "@icp-sdk/auth/client"
+import type { ReactNode } from "react"
+
+export function Providers({ children }: { children: ReactNode }) {
+  return (
+    <ReactorProvider
+      client={() =>
+        createClient({
+          network: "ic",
+          auth: (network) => new AuthClient(network),
+        })
+      }
+    >
+      {children}
+    </ReactorProvider>
+  )
+}
+```
+
+Who owns a client follows from when it was created, not from where the factory
+is written. A getter such as `client ??= createClient(...)` makes the first
+provider that calls it the owner. Create a shared client eagerly instead. A
+Server Component cannot pass the factory across the client boundary, so in
+Next.js the provider sits in a client module that the layout renders: see
+[SSR and hydration](/v4/guides/ssr/).
+
+An app that already uses TanStack Query keeps one `QueryClient` per tree,
+the client's. `ReactorProvider` provides `client.queryClient`, so the app's own
+queries, REST calls included, run on it: an error that is not a `ReactorError`
+is retried as TanStack Query retries it by default (up to 3 times in a
+browser, never on a server), and `client.dispose()` clears those queries
+along with the client's reads. Set other defaults on each query. A
+`QueryClientProvider` of the app's own nested inside the provider works too: a
+write invalidates its reads on the `QueryClient` it ran on as well as on the
+client's. That `QueryClient` lacks the client's dehydrate and hydrate defaults,
+so a server render dehydrates `client.queryClient`.
+
+### useClient
+
+`useClient()` returns the client of the nearest provider. It throws outside a
+provider. Call it in the body of each component that builds keys or read
+options, on every render:
+
+```tsx
+import { useClient } from "@ic-reactor/react"
+import { useQuery } from "@tanstack/react-query"
+import { actor, type Actor } from "./generated/icrc1"
+
+export function Fee({ id }: { id: string }) {
+  const client = useClient()
+  const ledger = client.canister<Actor>(actor, { id })
+  const fee = useQuery(client.queryOptions(ledger, "icrc1_fee"))
+  return <span>{fee.data?.toString() ?? "…"}</span>
+}
+```
+
+It follows the client's caller, so a component that calls it renders again on
+a sign-in, a switch of account and a sign-out, and builds the new caller's
+keys. A change of status that leaves the caller as it is renders nothing.
+
+It returns a view of the client for the caller the render shows (the anonymous
+one while a page hydrates): one object per caller, a new one when the caller
+changes, the same one on every render while it stays. List it in the
+dependencies of a `useMemo`, an effect or a callback built from it; React
+Compiler memoizes on it the same way, so what is memoized is built again for
+the new caller. Its `mutationOptions` send only as that caller: a write
+pressed before a switch reached the render is refused (`caller_changed`) and
+sends nothing. It is never the provider's client object, so compare two
+clients by their `queryClient`, and do not keep its result past its render.
+See [SSR and hydration](/v4/guides/ssr/).
+
+### useAuth
+
+`useAuth()` returns `{ status, principal, expiresAt?, signIn, signOut }`: the
+client's `AuthState` with sign-in and sign-out forwarded to the client. It
+renders a component once for each change of status, principal or `expiresAt`,
+and when a session ends by the clock. It is `"anonymous"` on
+a server and during a hydrating render. See [Auth](/v4/guides/auth/).
+
+## Life of the client
+
+- **StrictMode.** The development double-mount does not dispose a client in
+  use: disposal is scheduled for the next macrotask, and the second mount
+  cancels it.
+- **A render React throws away.** React runs no cleanup for a render it drops
+  before committing it, such as a provider's first render below a Suspense
+  boundary that suspends. A client the factory built for it is disposed once
+  that render's state is garbage collected (through a `FinalizationRegistry`,
+  in a browser).
+- **Replacing the client.** Only the factory of the first render is used.
+  Passing another function later does not rebuild the client. To replace the
+  client, give the provider another `key`.
+- **Activity.** If React shows a hidden `Activity` again after the client the
+  provider owns was disposed, the provider builds another one with the same
+  factory, and it starts with an empty cache. To keep the cache across hiding,
+  render the provider above the `Activity`, or give it a client the app owns.
+
+## Where to go next
+
+- [Auth](/v4/guides/auth/): `useAuth`, sign-in and caller changes.
+- [Reads](/v4/guides/reads/) and [Writes](/v4/guides/writes/): the options the
+  client builds for TanStack Query.
+- [SSR and hydration](/v4/guides/ssr/): one client per request, and the limits
+  of a signed-in reload.
+- [Testing](/v4/guides/testing/): a provider with a borrowed test client.
+- [Examples](/v4/examples/): the Vite wallet and the Next.js app.
+
+The guide for both packages is `llms.txt`, shipped in
+`node_modules/@ic-reactor/core/llms.txt`; the React package's own `llms.txt`
+points to it. The released 3.x package is documented on
+[Migrating from 3.x](/v4/migrating-from-3/).

package/docs/src/content/docs/packages/vite-plugin.mdx

@@ -0,0 +1,73 @@
+---
+title: "@ic-reactor/vite-plugin"
+description: "What @ic-reactor/vite-plugin exports, its peers, and how to install it"
+---
+
+`@ic-reactor/vite-plugin` generates the module that `meant gen` writes from a
+`.did` file, with `@meantjs/cli` in a child process, and it sets the `ic_env`
+cookie and the `/api` proxy under `vite dev` and `vite preview`. It adds no
+wrapper files, hooks or reactors.
+
+Its 4 line replaces the 0.15 plugin of the 3.x line, which generates reactor
+bindings with `@ic-reactor/codegen`: see
+[Migrating from 3.x](/v4/migrating-from-3/).
+
+## Install
+
+```sh
+npm install --save-exact @meantjs/schema@0.6.0
+npm install --save-dev --save-exact @meantjs/cli@0.5.1
+npm install --save-dev @ic-reactor/vite-plugin
+```
+
+## Exports
+
+The package has one entry, `@ic-reactor/vite-plugin`, in ESM and CommonJS. It
+exports two names, and there is no other subpath:
+
+| Name                     | Kind     | What it is                                                                  |
+| ------------------------ | -------- | --------------------------------------------------------------------------- |
+| `icReactor`              | function | `icReactor(options?)` returns the Vite plugin                               |
+| `IcReactorPluginOptions` | type     | The options: `canisters`, `injectEnvironment`, `failOnError`, `onGenerated` |
+
+```ts
+import { icReactor, type IcReactorPluginOptions } from "@ic-reactor/vite-plugin"
+import { defineConfig } from "vite"
+
+const options: IcReactorPluginOptions = {
+  canisters: { icrc1: { didFile: "did/icrc1.did" } },
+}
+
+export default defineConfig({ plugins: [icReactor(options)] })
+```
+
+## Peers
+
+| Peer            | Range                                              |
+| --------------- | -------------------------------------------------- |
+| `@meantjs/cli`  | exactly `0.5.1`                                    |
+| `@icp-sdk/core` | `^6.1.0`, optional                                 |
+| `vite`          | `^4.2.0`, `^5.0.0`, `^6.0.0`, `^7.0.0` or `^8.0.0` |
+
+Node `>=22.12.0`, as core and react.
+
+The CLI is pinned exactly because the plugin runs the CLI your app installs,
+and that CLI has to pair with the `@meantjs/schema` runtime the generated
+modules import. The plugin itself imports no `@ic-reactor` runtime package, so
+it can be used with the generated module alone. It loads `@icp-sdk/core` only
+to [fetch a `.did` from a live canister](/v4/guides/vite-plugin/#fetch-a-did-from-a-live-canister),
+when a `didFile` is not on disk; every app on `@ic-reactor/core` has it
+installed already.
+
+## Read next
+
+- [The Vite plugin](/v4/guides/vite-plugin/): options, generation, failures and
+  the local environment in full.
+- [Getting started](/v4/guides/getting-started/): install, generate and make a
+  first read and write.
+- [Vite wallet](/v4/examples/vite-wallet/): `network: "env"` and `{ name }`
+  targets on a local `icp` network.
+- [ICRC-1 ledger](/v4/examples/icrc-ledger/): three `.did` files generated into
+  one `outDir`, with `injectEnvironment: false`.
+- [@ic-reactor/core](/v4/packages/core/) and
+  [@ic-reactor/react](/v4/packages/react/): the runtime packages.