@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/evals/conditions/thin-guide/docs/llms.txt

@@ -0,0 +1,292 @@
+# candid-core + TanStack Query on the Internet Computer
+
+> How to call Internet Computer canisters with a module generated from the
+> canister's `.did` by `candid-core-cli gen`, `@candid-core/schema`'s
+> `createActor` over `@icp-sdk/core`'s `HttpAgent`, and TanStack Query used
+> directly. There is no framework in between: this guide is the set of rules
+> that framework would otherwise enforce. The `@candid-core/schema` and
+> `@candid-core/cli` READMEs next to this file are the API reference.
+
+## Imports
+
+```ts
+import { AnonymousIdentity, HttpAgent, type Identity } from "@icp-sdk/core/agent"
+import { Principal } from "@icp-sdk/core/principal"
+import { ActorError, createActor } from "@candid-core/schema/actor"
+import { httpTransport } from "@candid-core/schema/transport-icp"
+import { actor, type Actor } from "./generated/icrc1" // the generated module
+```
+
+The generated module (`src/generated/icrc1.ts`) exports one type and one
+schema per Candid type, the service schema `actor`, and `type Actor`: one
+async function per method, with its argument and result types. Do not edit
+it.
+
+## Setup
+
+```ts
+const agent = HttpAgent.createSync({ host, identity, rootKey, shouldFetchRootKey })
+const ledger = createActor<Actor>(actor, "ryjl3-tyaaa-aaaaa-aaaba-cai", httpTransport({ agent }))
+```
+
+`host` and the root key:
+
+- mainnet — `host: "https://icp-api.io"`; no `rootKey`, no fetching.
+- a local replica — `host: "http://127.0.0.1:4943"` (or yours). Pass
+  `rootKey` when you have it, and then never fetch one; without it,
+  `shouldFetchRootKey: true` fetches it from the replica. Fetch only when the
+  host is local (`localhost`, `127.0.0.1`, `[::1]`), never from any other
+  host.
+
+The identity:
+
+- a fixed `Identity` (scripts, servers, tests); omit it for anonymous.
+- a sign-in source — anything with `getIdentity(): Identity` (the anonymous
+  identity while signed out), `isAuthenticated(): boolean` and
+  `subscribe(listener): () => void` (called on every sign-in, sign-out and
+  principal switch). Read it at the moment you act.
+
+Who is calling, and may they write:
+
+| Question               | Answer                                                                  |
+| ---------------------- | ----------------------------------------------------------------------- |
+| the caller's principal | `identity.getPrincipal().toText()` (`"2vxsx-fae"`, anonymous, when signed out) |
+| may a write be sent    | `auth.isAuthenticated() && !identity.getPrincipal().isAnonymous()`     |
+| when did it change     | `auth.subscribe(fn)`                                                    |
+
+Build one agent (and one actor) per identity, and never change an agent's
+identity afterwards (no `replaceIdentity`). A call made as Alice then always
+goes out through Alice's agent, however the sign-in state changes while it
+is in flight.
+
+In React, re-render on identity changes with `useSyncExternalStore`, and key
+the agent on the identity:
+
+```tsx
+const identity = useSyncExternalStore(auth.subscribe, auth.getIdentity)
+const signedIn = auth.isAuthenticated() && !identity.getPrincipal().isAnonymous()
+const ledger = useMemo(() => makeLedger(identity), [identity])
+```
+
+Build agents and actors once per identity (module scope, or `useState` /
+`useMemo`), not on every render.
+
+## Values
+
+The actor takes and returns the generated module's types:
+
+| Candid                       | Value                                               |
+| ---------------------------- | --------------------------------------------------- |
+| `nat`, `int`, `nat64`, `int64` | `bigint` (never `number`)                         |
+| `nat8`..`nat32`, `int8`..`int32`, floats | `number`                                |
+| `text`                       | `string`                                            |
+| `bool`                       | `boolean`                                           |
+| `principal`                  | in: `Principal.fromText(text)`; out: an object with only `toText()` |
+| `blob` / `vec nat8`          | `Uint8Array`                                        |
+| `opt T`                      | `T \| null` (the property is always present)        |
+| `vec T`                      | `T[]`                                               |
+| `record { a : T }`           | `{ a: T }` — every field present                    |
+| `variant { A : T; B }`       | `{ tag: "A"; value: T } \| { tag: "B" }`            |
+
+Make principals from user input with `Principal.fromText(text)`, which throws
+for invalid text; catch it and refuse the input. A principal in a reply is not
+a `Principal` instance: call `.toText()` on it.
+
+Arguments are positional, as in `type Actor`: `ledger.method(arg)`; a method
+with no arguments takes none.
+
+### Results
+
+Replies come back whole. A method whose result is `variant { Ok : T; Err : E }`
+resolves with `{ tag: "Ok", value }` or `{ tag: "Err", value }`; nothing
+throws for `Err`. Switch on the tag (or use `unwrapResult` from
+`@candid-core/schema/validate`).
+
+```ts
+// icrc1_transfer : (TransferArg) -> (variant { Ok : nat; Err : TransferError })
+const result = await ledger.icrc1_transfer(arg)
+if (result.tag === "Ok") {
+  const blockIndex: bigint = result.value
+}
+```
+
+## Reads
+
+Query methods go through `useQuery` (or `queryClient.fetchQuery`):
+
+```tsx
+import { skipToken, useQuery } from "@tanstack/react-query"
+
+const caller = identity.getPrincipal().toText()
+const profile = useQuery({
+  queryKey: ["ic", host, caller, BACKEND_ID, "get_profile", userId],
+  queryFn: userId ? () => backend.get_profile(Principal.fromText(userId)) : skipToken,
+})
+```
+
+`skipToken` is TanStack Query's; pass it instead of a function while the
+arguments do not exist yet.
+
+Key every read by
+`["ic", network, callerPrincipal, canisterId, method, ...args]`, with args as
+text (`principal.toText()`, `bigint.toString()`): TanStack Query hashes keys
+with `JSON.stringify`, which throws on a `bigint`. Because the caller is in
+the key, one principal's cached answer is never served to another: after a
+sign-in, sign-out or switch, the new caller's key has no data until it loads,
+and `data` is `undefined` meanwhile. Keep it that way: options that carry data
+from one key to the next (`placeholderData: keepPreviousData`, `initialData`
+from another key) would show the previous principal's data.
+
+Reads may keep TanStack Query's default retries: a query changes nothing. Add
+ordinary options as you need them (`staleTime`, `select`).
+
+`Principal.fromText` throws while you build the key if the text is not a
+principal; validate input before it reaches a query.
+
+## Writes
+
+Update methods go through `useMutation`, or are called directly:
+
+```tsx
+const transfer = useMutation({
+  mutationFn: (arg: TransferArg) => ledger.icrc1_transfer(arg),
+  onSettled: (_data, error) => {
+    // after a success, and after a failure that may have executed
+    if (!error || mayHaveExecuted(error)) {
+      return queryClient.invalidateQueries({ queryKey: ["ic", host] })
+    }
+  },
+})
+if (signedIn) transfer.mutate(arg)
+
+await ledger.icrc1_transfer(arg)                // direct call, outside React
+```
+
+- Invalidate the reads a write can change (for every caller) after a success,
+  and also after a failure that may have executed, because the write may have
+  happened. Nothing else is needed to show fresh data after an unknown outcome.
+- Do not retry a write. Mutations retry nothing by default; keep it that way.
+  If you must, re-send only after a failure that proves the canister never
+  received the request (see Errors: reject code 2, or an HTTP 4xx other than
+  408); any other failure is final.
+- A write is sent as whoever is signed in when it runs. If nobody is (or the
+  identity is anonymous), refuse it before calling anything.
+- Call update methods only from `useMutation` or directly, never from
+  `useQuery`; call query methods from `useQuery` or directly.
+
+## Errors
+
+The actor throws `ActorError` for a codec failure and passes `@icp-sdk/core`'s
+agent errors through untouched. A failed write either certainly had no
+effect, or may have executed:
+
+| What was thrown                                                        | Meaning                                                              | May have executed      |
+| ---------------------------------------------------------------------- | -------------------------------------------------------------------- | ---------------------- |
+| `ActorError`, message starting `encode`                                | the arguments could not be encoded; nothing was sent                 | no                     |
+| your own refusal (not signed in, invalid input)                        | nothing was sent                                                     | no                     |
+| agent error, `code.name === "HttpErrorCode"`, `code.status` 4xx but not 408 | the replica or boundary refused the request                     | no                     |
+| agent error with `code.rejectCode` 1, 2 or 3                           | the IC rejected the call before any canister code ran (2 is transient) | no                   |
+| agent error with `code.rejectCode` 4 or 5                              | the canister's own code rejected (4) or trapped (5); it may have committed state first | yes (for a write) |
+| any other agent error (`kind` `"Transport"`, `"Protocol"`, `"Trust"`, `"Unknown"`: network drop, timeout, 5xx, 408) | a write went out and no trustworthy answer came back | yes |
+| `ActorError`, message starting `decode`                                | a reply arrived but did not decode as the result type                | yes (for a write)      |
+| an `Err` reply (not thrown)                                            | the canister returned `Err`                                          | no                     |
+
+Read agent errors structurally — `kind`, `code.name`, `code.rejectCode`,
+`code.status` — so an error from another copy of the agent classifies the
+same way:
+
+```ts
+function mayHaveExecuted(error: unknown): boolean {
+  if (error instanceof ActorError) return !error.message.startsWith("encode")
+  const code = (error as { code?: { name?: unknown; rejectCode?: unknown; status?: unknown } })?.code
+  if (typeof code?.rejectCode === "number") return code.rejectCode > 3
+  if (code?.name === "HttpErrorCode" && typeof code.status === "number") {
+    return !(code.status >= 400 && code.status < 500 && code.status !== 408)
+  }
+  return true
+}
+```
+
+For a query, `httpTransport` throws a plain `Error` naming the reject code in
+its message; a query changes nothing, so it never "may have executed".
+
+## Outside React
+
+```ts
+import { QueryClient } from "@tanstack/query-core"
+
+const queryClient = new QueryClient()
+const key = ["ic", host, caller, LEDGER_ID, "icrc1_balance_of", owner.toText()]
+const balance = await queryClient.fetchQuery({ queryKey: key, queryFn: () => ledger.icrc1_balance_of(account) })
+await queryClient.invalidateQueries({ queryKey: ["ic", host] })
+const fresh = await ledger.icrc1_balance_of(account)   // no cache at all
+```
+
+Direct calls never touch a cache; use them in scripts and services that must
+always see current state.
+
+## Example
+
+```tsx
+import { useMemo, useState, useSyncExternalStore } from "react"
+import { QueryClient, QueryClientProvider, skipToken, useMutation, useQuery, useQueryClient } from "@tanstack/react-query"
+import { HttpAgent, type Identity } from "@icp-sdk/core/agent"
+import { createActor } from "@candid-core/schema/actor"
+import { httpTransport } from "@candid-core/schema/transport-icp"
+import { actor, type Actor } from "./generated/backend"
+
+const HOST = "https://icp-api.io"
+const makeBackend = (identity: Identity) =>
+  createActor<Actor>(actor, BACKEND_ID, httpTransport({ agent: HttpAgent.createSync({ host: HOST, identity }) }))
+
+export function App({ auth }: { auth: AuthLike }) {
+  const [queryClient] = useState(() => new QueryClient())
+  return (
+    <QueryClientProvider client={queryClient}>
+      <Profile auth={auth} />
+    </QueryClientProvider>
+  )
+}
+
+function Profile({ auth }: { auth: AuthLike }) {
+  const queryClient = useQueryClient()
+  const identity = useSyncExternalStore(auth.subscribe, auth.getIdentity)
+  const me = identity.getPrincipal()
+  const signedIn = auth.isAuthenticated() && !me.isAnonymous()
+  const backend = useMemo(() => makeBackend(identity), [identity])
+  const profile = useQuery({
+    queryKey: ["ic", HOST, me.toText(), BACKEND_ID, "get_profile", me.toText()],
+    queryFn: signedIn ? () => backend.get_profile(me) : skipToken,
+  })
+  const rename = useMutation({
+    mutationFn: (name: string) => backend.set_name(me, name),
+    onSettled: (_d, error) =>
+      !error || mayHaveExecuted(error) ? queryClient.invalidateQueries({ queryKey: ["ic", HOST] }) : undefined,
+  })
+
+  if (!signedIn) return <p>Sign in</p>
+  if (profile.data === undefined) return <p>Loading…</p>
+  return (
+    <>
+      <p>{profile.data.name}</p>
+      <button disabled={rename.isPending} onClick={() => rename.mutate("Ada")}>Rename</button>
+      {rename.error && <p>{mayHaveExecuted(rename.error) ? "Unknown outcome" : rename.error.message}</p>}
+    </>
+  )
+}
+```
+
+## Do not
+
+- Pass principal text where a principal is expected: use
+  `Principal.fromText(text)`.
+- Convert `bigint` values to `number`, or put a `bigint` in a query key.
+- Add `retry` to a write, or call a write from `useQuery`: TanStack Query may
+  run a query's function again whenever it refetches, and every run of an
+  update executes again.
+- Leave the caller out of a key, or carry data across keys
+  (`keepPreviousData`, cross-key `initialData`).
+- Build agents or actors inside render without `useMemo`/`useState`, or
+  change an agent's identity once built.
+- Send a write while nobody is signed in, or as the anonymous identity.
+- Treat every failed write as "not executed": classify it as above.

package/evals/conditions/v3/condition.json

@@ -0,0 +1,9 @@
+{
+  "name": "v3",
+  "library": "Available library: IC Reactor 3.13.0 as published — `@ic-reactor/core`, and `@ic-reactor/react` for React (it re-exports core) — on `@icp-sdk/core`, `@icp-sdk/auth` and TanStack Query. The ledger's Candid declarations (`idlFactory`, `_SERVICE`) are in `src/declarations/`. Its documentation is in `docs/`; read it before you start.",
+  "docs": [
+    "docs/llms-full.txt",
+    "docs/ic-reactor-core.llms.txt",
+    "docs/ic-reactor-react.llms.txt"
+  ]
+}

package/evals/conditions/v3/docs/ic-reactor-core.llms.txt

@@ -0,0 +1,232 @@
+# @ic-reactor/core
+
+> Framework-agnostic runtime for calling Internet Computer canisters with
+> typed methods, TanStack Query caching, typed errors and exact token amounts.
+> No React: React apps install `@ic-reactor/react`, which re-exports all of this.
+
+Applies to `@ic-reactor/core` 3.13.0.
+
+Read this file from `node_modules/@ic-reactor/core/llms.txt` when writing code
+against the installed version. The complete guide for every package is
+https://ic-reactor.b3pay.net/llms-full.txt, and behaviour changes are in
+https://github.com/B3Pay/ic-reactor/blob/main/CHANGELOG.md.
+
+## Install
+
+```bash
+pnpm add @ic-reactor/core @icp-sdk/core @tanstack/query-core
+```
+
+## Setup and Usage
+
+```ts
+import {
+  ClientManager,
+  Reactor,
+  isCanisterError,
+  reactorRetry,
+} from "@ic-reactor/core"
+import { QueryClient } from "@tanstack/query-core"
+import { canisterId, idlFactory, type _SERVICE } from "./declarations/backend"
+
+const clientManager = new ClientManager({
+  queryClient: new QueryClient({
+    defaultOptions: { queries: { retry: reactorRetry } },
+  }),
+  agentOptions: { host: "https://ic0.app" },
+})
+const backend = new Reactor<_SERVICE>({
+  clientManager,
+  idlFactory,
+  name: "backend",
+  canisterId,
+})
+
+// A cached, deduplicated read
+export const getProfile = (id: string) =>
+  backend.fetchQuery({ functionName: "get_profile", args: [id] })
+
+// An update resolves with the Ok value and throws a CanisterError for Err
+export async function rename(name: string) {
+  try {
+    const profile = await backend.callMethod({
+      functionName: "update_profile",
+      args: [{ name }],
+    })
+    await backend.invalidateQueries({ functionName: "get_profile" })
+    return profile
+  } catch (error) {
+    if (isCanisterError(error)) return `Refused: ${error.code}` // "NotFound"
+    throw error // CallError: network, agent, certificate or trap
+  }
+}
+```
+
+## When to Use What
+
+| Need                                         | Use                                                                        |
+| -------------------------------------------- | -------------------------------------------------------------------------- |
+| Raw Candid values (`bigint`, `Principal`)    | `new Reactor<_SERVICE>({ clientManager, idlFactory, name, canisterId })`   |
+| Strings for display and forms, validators    | `new DisplayReactor<_SERVICE>(...)` (adds zod)                             |
+| A cached, deduplicated read                  | `reactor.fetchQuery({ functionName, args })`                               |
+| An update, or a read that skips the cache    | `reactor.callMethod({ functionName, args })`                               |
+| Read or refresh the cache                    | `reactor.getQueryData(...)`, `await reactor.invalidateQueries(...)`        |
+| Another canister with the same interface     | `reactor.forCanister(canisterId)`                                          |
+| One agent and cache for several canisters    | one `ClientManager`, passed to every reactor                               |
+| Act as an identity                           | `clientManager.updateAgent(identity)`                                      |
+| Your own `queryClient.fetchQuery` of a query | wrap it in `clientManager.fetchAcrossIdentitySwitch(() => ...)`            |
+| Show or read token amounts                   | `formatTokenAmount`, `parseTokenAmount`                                    |
+| Validate typed principal text                | `isPrincipalText(text.trim())`                                             |
+| Tests                                        | `installFakeReplica`, `createTestCanister` from `@ic-reactor/core/testing` |
+| React                                        | `@ic-reactor/react` instead                                                |
+
+## Reactors and Values
+
+- Pass the service type (`new Reactor<_SERVICE>(...)`). Without it every
+  argument and result is `any` (`unknown` on a `DisplayReactor`).
+- A `Result` is unwrapped: `callMethod` and `fetchQuery` resolve with the `Ok`
+  value and throw a `CanisterError` for an `Err`.
+- `DisplayReactor` maps `nat`/`int`/`nat64`/`int64` to `string`, `principal`
+  to text, `blob` to hex, `opt T` to `T | undefined` and a variant to
+  `{ _type: "A", A: value }` (`{ _type: "A" }` for a case without a value:
+  switch on `_type`). `fromZodSchema(schema, { async: true })` builds
+  an async validator, which runs only in `validate()` and
+  `callMethodWithValidation()`.
+- Floats display as numbers, and `NaN`, `±Infinity` and `-0` are sent back as
+  read; JSON writes `NaN`/`±Infinity` as `null` and `-0` as `0`.
+- `vec record { text; T }` displays as an object: a repeated key keeps its last
+  value. Use `Reactor` where repeated keys or their order matter.
+- `reactor.forCanister(canisterId)` returns a memoized sibling of the same
+  class on the same `ClientManager`, with the same interface and validators,
+  whose calls and keys use its own canister.
+- Types: `ReactorArgsOf<typeof r, "method">`, `ReactorDataOf<...>`,
+  `ReactorErrorOf<...>`, `ServiceOf<typeof r>`, `TransformOf<typeof r>`.
+
+## Cache and Identity
+
+- Query keys start with the canister id and the method name; build one with
+  `reactor.generateQueryKey(...)`, never by hand.
+- `invalidateQueries` returns TanStack Query's `Promise<void>`: `await` it to
+  wait for the active matches to refetch (a failed refetch does not reject
+  it), or prefix a call you do not wait for with `void`.
+- A sign-in or sign-out (`updateAgent` with another principal) cancels the
+  fetches in flight of every canister the manager has a reactor for, removes
+  their unobserved cache entries and refetches the rest; a renewed delegation
+  for the same principal keeps the cache.
+  `fetchQuery` then fetches again as the new principal instead of rejecting,
+  and after three switches in a row rejects with a `CallError`.
+
+## Token Amounts and Principals
+
+- Ledger amounts are base units: a `bigint` from `Reactor`, integer text from
+  `DisplayReactor`. Never use `Number`, `parseFloat`, `Math.pow` or `toFixed`:
+  `Math.floor(Number("0.29") * 10 ** 8)` is 28999999.
+- `formatTokenAmount(value, decimals, options?)` takes the value and
+  `icrc1_decimals` as returned. Options: `maxFractionDigits` (truncates unless
+  `roundingMode: "halfExpand"`), `minFractionDigits`, `trimTrailingZeros`,
+  `locale`, `useGrouping`. Without `locale` it writes plain text (`"1234.5"`).
+- `parseTokenAmount(text, decimals)` returns a `bigint`; it throws a
+  `TypeError` for text that is not digits with one `.`, and a `RangeError` for
+  more fraction digits than the token has or a negative amount
+  (`{ allowNegative: true }` for an `int`). Send `amount.toString()` to a
+  `DisplayReactor`.
+- `isPrincipalText(text.trim())` accepts canonical principal text of at most
+  29 bytes and never throws. A `DisplayReactor` takes the text; a `Reactor`
+  takes `Principal.fromText(text)`.
+- `jsonToString(value)` prints a raw value: bigints as digits, principals as
+  text, blobs as hex.
+
+```ts
+import { formatTokenAmount, parseTokenAmount } from "@ic-reactor/core"
+import { ledger } from "./ledger" // a DisplayReactor of an ICRC-1 ledger
+
+export async function send(owner: string, input: string, decimals: number) {
+  const amount = parseTokenAmount(input, decimals) // "0.29", 8 -> 29000000n
+  await ledger.callMethod({
+    functionName: "icrc1_transfer",
+    args: [{ to: { owner }, amount: amount.toString() }], // display form
+  })
+}
+export const show = (balance: string, decimals: number) =>
+  formatTokenAmount(balance, decimals, { maxFractionDigits: 4 }) // "1.2345"
+```
+
+## Errors and Retries
+
+- `CanisterError`: the canister returned `Err`. Read the value on `.err` and
+  the variant (or API `code`) on `.code`; `.details` is the API payload's
+  `details` as decoded.
+- `CallError`: network, agent, certificate, a trap, or a validator that threw
+  (its error is the `cause`).
+- `ValidationError`: a `DisplayReactor` validator refused the arguments.
+- Use `isCanisterError`, `isCallError` and `isValidationError`; they also
+  recognise errors from another copy of the package.
+- `reactorRetry` retries transport, certificate, HTTP 5xx/408/429 and
+  `SysTransient`/`SysUnknown` failures up to 3 times, never a
+  `CanisterError`, a `ValidationError`, an encode/decode failure or another
+  HTTP 4xx. Set it as `defaultOptions.queries.retry` on a `QueryClient` you
+  create.
+- `reactorRetry` and `reactorUpdateRetry` retry only in a browser: where there
+  is no `window` (Node, server rendering, a web worker) they return `false`,
+  as TanStack Query retries nothing on a server by default. The agent still
+  resends a failed HTTP request itself. For query retries in a Node script,
+  pass the predicate:
+  `retry: (count, error) => count < 3 && isRetryableReactorError(error)`.
+- Each attempt of an update is a new call the canister runs.
+  `reactorUpdateRetry` retries only a `SysTransient` rejection, which proves
+  the call never ran; a query of an update method that sets no `retry` uses
+  that rule within the `QueryClient`'s retry default.
+
+## Network and the ic_env Cookie
+
+- In a browser with no `agentOptions.host`, the agent calls the page origin on
+  a local page (`localhost`, loopback), a Codespaces or Gitpod domain (network
+  `"remote"`) or an IC boundary domain, and mainnet otherwise.
+- `ClientManager` trusts the `ic_env` cookie (root key, Internet Identity
+  provider, `PUBLIC_CANISTER_ID:<name>`) only on loopback and `localhost`
+  hosts. Anywhere else, including Codespaces and Gitpod, pass
+  `allowEnvConfig: true` only for a host you control; without it a reactor with
+  no `canisterId` throws rather than read the id from the cookie.
+- Off mainnet, `initialize()` fetches the replica's root key, unless you pass
+  `agentOptions.rootKey`, which is kept (`clientManager.explicitRootKey`).
+- `isMainnetHost` recognises the boundary domains only; never use it as a
+  "safe to trust local configuration" test.
+
+## Testing
+
+`installFakeReplica({ canisters: { [id]: createTestCanister<_SERVICE>(idlFactory, handlers) } })`
+from `@ic-reactor/core/testing` replaces the global `fetch`. Install it before
+any `ClientManager` is built, pass `agentOptions: { host: replica.host }` (or
+no host on either side), and call `replica.restore()` in `afterEach`.
+Handlers get the decoded argument tuple and `{ caller }` and return raw Candid
+values; return `{ Err: ... }` for a `CanisterError` and throw for a
+`CallError`. `replica.requests` lists every request. The entry signs with
+`@noble/curves`, an optional peer that `@icp-sdk/core` already installs.
+
+## Do Not
+
+- Leave out the `<_SERVICE>` type argument or cast results to `any`.
+- Do token math with `Number`, `parseFloat`, `Math.pow` or `toFixed`.
+- Retarget a shared reactor with `setCanisterId`; use `forCanister`.
+- Hand-write query keys.
+- Call an update method through `fetchQuery` unless repeating it is safe.
+- Give an update call a numeric `retry`; use `reactorUpdateRetry`.
+- Build a reactor or `ClientManager` at module scope on a server that serves
+  several users: keys carry no principal, so the cache is shared.
+- Set `allowEnvConfig: true` for a host you do not control.
+- Stub a reactor with `as unknown as Reactor` in tests.
+- Edit generated declarations; regenerate them from the `.did`.
+
+## Docs
+
+- Core package: https://ic-reactor.b3pay.net/v3/packages/core.md
+- ClientManager: https://ic-reactor.b3pay.net/v3/reference/ClientManager.md
+- Reactor: https://ic-reactor.b3pay.net/v3/reference/Reactor.md
+- DisplayReactor: https://ic-reactor.b3pay.net/v3/reference/DisplayReactor.md
+- Utilities: https://ic-reactor.b3pay.net/v3/reference/Utilities.md
+- Error handling: https://ic-reactor.b3pay.net/v3/guides/error-handling.md
+- Local development: https://ic-reactor.b3pay.net/v3/getting-started/local-development.md
+- Testing kit: https://ic-reactor.b3pay.net/v3/reference/testing.md
+- Index of all docs: https://ic-reactor.b3pay.net/llms.txt
+- Full guide: https://ic-reactor.b3pay.net/llms-full.txt
+- Agent skill for Claude Code and other agents: https://github.com/B3Pay/ic-reactor/tree/main/skill-packages/ic-reactor