@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/CLAUDE.md

@@ -0,0 +1,93 @@
+# CLAUDE.md — IC Reactor Project Context
+
+This file gives Claude-based agents the context of this repository. Task
+routing and verification by change type are in [`AGENTS.md`](./AGENTS.md).
+
+## Branches
+
+- **`main`** (this branch) is the line of ic-reactor 4. Its release lane
+  publishes a stable 4.x version under npm's `latest` dist-tag and a 4.x
+  prerelease under `beta` (`scripts/release-tag.mjs`).
+- **`v3`** is the 3.x line, cut from `main` at the 4.0 GA flip: security fixes
+  only, until 90 days after the 4.0 release, released with its own
+  workflows. `v4`, the branch 4 was developed on until GA, was retired on
+  2026-10-26.
+
+Open pull requests for ic-reactor 4 against `main`, and 3.x security fixes
+against `v3`.
+
+## What ic-reactor 4 is
+
+A thin layer over a module that `meant gen` generates from a `.did`
+file, plus one consumer guide. There are no typed handles. No package code on
+this branch is written against unpublished Meant shapes: core's peer
+`@meantjs/schema` and the Vite plugin's peer `@meantjs/cli` are pinned
+exactly to published stable releases.
+
+## Packages on this branch
+
+| Package                   | Directory              | State on `main`                                                                                                                |
+| ------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `@ic-reactor/core`        | `packages/core`        | `4.1.1`; `createClient`, `ReactorError`, the units helpers and their types (13 names), and `./testing` with `createTestClient` |
+| `@ic-reactor/react`       | `packages/react`       | `4.1.1`; `ReactorProvider`, `useClient`, `useAuth` and `ReactorProviderProps`, over a core client                              |
+| `@ic-reactor/vite-plugin` | `packages/vite-plugin` | `4.1.1`; generates the module with `@meantjs/cli` in a child process, and sets the `ic_env` cookie and `/api` proxy            |
+| `@ic-reactor/mcp`         | `packages/mcp`         | `4.1.1`; the `ic-reactor-mcp` command, an MCP server for any canister that sends an update only after the person approves it   |
+
+Not in this tree: `@ic-reactor/parser`, `@ic-reactor/codegen` and
+`@ic-reactor/cli` (replaced by `meant gen`), and `@ic-reactor/candid` (frozen at
+3.x, published from `v3`). The 3.x example apps are on `v3`; the five ic-reactor
+4 examples are in `examples/` (`icrc-ledger`, `vite-wallet`, `next-ssr`,
+`node-agent-tool`, `canister-studio`).
+
+## AI context
+
+- `packages/core/llms.txt` is the one consumer guide, shipped in core's
+  tarball; it must not describe an API that is not built yet.
+  `packages/react/llms.txt` points at it, and
+  `skill-packages/ic-reactor/SKILL.md`, the one consumer skill, adds only
+  workflow. `node evals/harness/check-docs.mjs "$PWD/packages/core/llms.txt"`
+  must find no hidden-test name or literal in the guide.
+- There is no root `llms.txt` or `llms-full.txt` in this tree. The docs
+  deploy serves `packages/core/llms.txt` as the site's `/llms.txt`, and keeps
+  the frozen 3.x `llms-full.txt` from `v3` at `/llms-full.txt` and under `/v3/`.
+- `pnpm check:ai-context` checks the version stamps and docs links of
+  `scripts/ai-context-files.js`, and that none of the 34 removed 3.x names
+  (`scripts/removed-v3-names.js`) appears outside a "Removed in 4.0" section.
+  `pnpm check:snippets` compiles the code fences of the same files.
+- The hand-written docs pages follow the removed-names rule as well; only
+  `migrating-from-3.mdx` links `/v3/`, and a page names no `@ic-reactor`
+  version. `pnpm check:snippets:docs` compiles their fences.
+
+## Docs
+
+The docs site in `docs/` is built under `/v4/` (`base` in
+`docs/astro.config.mjs`). Its pages are a module of b3pay.net, served at
+`https://b3pay.net/docs/ic-reactor/` (`b3pay-module.json`,
+`.github/workflows/b3pay-site.yml`). `.github/workflows/docs.yml` deploys
+ic-reactor.b3pay.net from `main` (`scripts/assemble-docs-site.mjs` assembles
+it): `/v3/`, rebuilt from the `v3` branch, and `/v2/` stay there, and each
+`/v4/` and `/candid-core/` page sends readers to its page on b3pay.net. The
+deploy stops when b3pay.net does not serve IC Reactor's docs, with the API
+reference, or Meant's.
+
+## Development
+
+```bash
+pnpm install          # pnpm is pinned by packageManager; corepack picks it up
+pnpm build            # Build the packages
+pnpm test             # Run the package tests
+pnpm size             # Tight size limits, peers left out and included (CI gate; build first)
+pnpm typecheck        # Type-check every package and e2e/ (CI gate)
+pnpm lint             # ESLint over packages/*/src and tests (CI gate; build first)
+pnpm format:check     # Prettier over the repo (CI gate)
+pnpm check:ai-context # AI context versions and docs links (CI gate)
+pnpm check:stack      # Meant pins and mentions against stack.json (CI gate)
+pnpm check:snippets   # Compile the ts/tsx snippets of the READMEs and AI-context files (CI gate; build first)
+pnpm check:exports    # Built entries against scripts/export-budget.mjs (CI gate; build first)
+pnpm verify:traps     # Each @ts-expect-error of traps.test-d.ts bites (CI gate)
+pnpm verify:faults    # Each test of scripts/faults.json fails under its fault (CI gate)
+pnpm test:scripts     # The gates' own tests (CI gate; build first)
+pnpm verify:packages  # Pack and verify the published artifacts
+pnpm test:examples:published # Each example installed from npm against the published packages (own CI workflow)
+pnpm verify:peer-floors # Lowest peers and oldest TypeScript (CI gate; build first)
+```

package/CNAME

@@ -0,0 +1 @@
+ic-reactor.b3pay.net

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,7 @@
+# Contributor Covenant Code of Conduct
+
+This project follows the Contributor Covenant. By participating, you are expected to uphold this code. Please be respectful, considerate, and collaborative.
+
+For the full Code of Conduct, see: https://www.contributor-covenant.org/version/2/1/code_of_conduct/
+
+If you experience or witness unacceptable behavior, please contact the maintainers at `B3Pay` on GitHub or open an issue.

package/CONTRIBUTING.md

@@ -0,0 +1,433 @@
+# Contributing to IC Reactor
+
+Thanks for your interest in contributing! This project uses pnpm workspaces. Below are the common workflows and expected standards.
+
+## Branches
+
+- **`main`** is the line of ic-reactor 4. Open pull requests for new work
+  against `main`. It releases 4.x: stable versions under npm's `latest`,
+  prereleases (`4.1.0-beta.N`) under `beta`.
+- **`v3`** is the 3.x line, cut from `main` at the 4.0 GA flip. It takes
+  security fixes only, until 90 days after the 4.0 release, and 3.x security
+  releases are tagged from it with its own workflow files. Open a 3.x security
+  fix against `v3`.
+
+CI, e2e, CodeQL and dependency review run on pull requests to either branch,
+each with the workflow files of its own line.
+
+## Quickstart
+
+1. Fork the repository and clone it:
+
+```bash
+git clone https://github.com/<your-username>/ic-reactor.git
+cd ic-reactor
+git remote add upstream https://github.com/B3Pay/ic-reactor.git
+```
+
+2. Install dependencies:
+
+```bash
+pnpm install
+```
+
+3. Run the build and tests locally:
+
+```bash
+pnpm build
+pnpm test
+```
+
+4. Format files (automatically run on commit via Husky):
+
+```bash
+pnpm format
+```
+
+You can check formatting without modifying files:
+
+```bash
+pnpm format:check
+```
+
+Both scripts cover the whole repo. Exclusions live in one place,
+`.prettierignore`, which the pre-commit hook honours too, so the hook and the
+CI gate operate on exactly the same set of files.
+
+5. Run the remaining CI gates before opening a PR:
+
+```bash
+pnpm check:ai-context  # versions, package stamps and docs links in the AI guides
+pnpm check:stack       # Meant pins and mentions against stack.json
+pnpm check:snippets    # compiles the ts/tsx snippets of the guides and READMEs
+pnpm check:snippets:docs  # the same, plus the docs site's pages (needs the examples installed)
+pnpm lint              # ESLint over packages/*/src and packages/*/tests
+pnpm typecheck         # every package and e2e/, including their tests
+pnpm size              # gzipped size limits, see [Size budget](#size-budget)
+```
+
+`pnpm check:snippets`, `pnpm check:snippets:docs` and `pnpm lint` read the
+packages' built declarations, and `pnpm size` measures their built `dist`, so run `pnpm build` first. See [Code snippets](#code-snippets) for what to do
+when a snippet fails.
+
+If you touched `packages/` or `examples/`, also type-check and build every
+example app. `tsc` never loads a bundler, so an example can type-check cleanly
+and still fail to build:
+
+```bash
+pnpm typecheck:examples
+pnpm build:examples
+```
+
+If you touched `docs/`, `packages/` or `examples/`, run the docs gate. CI lints
+the MDX, checks the example pages against `examples/`, builds the site and
+crawls it for broken links. The API reference is generated from package
+sources, so a source change can break the docs build too:
+
+```bash
+pnpm --dir docs run lint:mdx
+pnpm docs:check-examples   # sandbox links, file= targets and index cards
+pnpm docs:build
+pnpm docs:check-links   # crawls docs/dist, so run it after docs:build
+```
+
+The pages link Candid Core's site, which the deploy serves at `/candid-core/`
+from a build of B3Pay/Meant. To check those links as CI does, build that
+site and name it (an absolute path):
+
+```bash
+git clone https://github.com/B3Pay/Meant ../Meant
+node ../Meant/website/build.mjs
+CANDID_CORE_SITE="$PWD/../Meant/website/dist" pnpm docs:check-links
+```
+
+If you changed a package's `exports`, `files`, build output, or module format,
+also run:
+
+```bash
+pnpm verify:packages
+```
+
+It packs each publishable package, installs the tarballs into a scratch project
+outside the workspace, imports and requires every entry point in real Node, and
+runs `publint` + `attw`. Nothing else in CI can catch a broken published
+artifact, because in-repo consumers resolve through workspace symlinks.
+
+## The Meant pins
+
+`stack.json` names the Meant release this branch is tested against: an exact
+stable version of `@meantjs/schema` and of `@meantjs/cli`. The rest of the
+tree follows it. `pnpm check:stack` (a CI step) reads each tracked
+`package.json`, Markdown, MDX and text file and the two files that pin in
+code, and fails on each of these that names another version, a range
+included:
+
+- a `package.json` entry keyed by the package: a dependency of any kind or an
+  override, `parent>package` and `package@range` keys included;
+- an `@meantjs/<name>@<version>` in a `package.json` value or a Markdown,
+  MDX or text file: an install line, a script's `npx`, an `npm:` alias, a CDN
+  URL;
+- a docs peer-table row that names the package and says exactly `<version>`;
+- the two pins in code: `MEANT_CLI_VERSION` in
+  `packages/vite-plugin/src/generate.ts` and the `@meantjs/schema` entry of
+  `scripts/export-budget.mjs`.
+
+A version in any other file (a `.ts` test, a workflow) is not read. It also
+fails when no `package.json` outside the frozen paths pins a package that
+`stack.json` lists, and when a frozen path holds no tracked file. Changelogs,
+symlinks and the paths of the manifest's `frozen` list keep the versions they
+have: the changelogs record what each release shipped with, and `evals/`
+pins what its conditions were measured with.
+
+ic-reactor installs Meant from npm, and only a published stable release. So
+Meant publishes first, and the repin is a pull request of its own:
+
+1. Change the versions in `stack.json`. The examples move with the rest of
+   the tree: in the workspace they run on this branch's packages, whose peers
+   are the new release, and an example left on the old one fails to
+   type-check against them (the Type Check Examples job, and the downstream
+   check a Meant release runs on this repository). Outside the workspace,
+   `pnpm test:examples:published` installs them with the published
+   ic-reactor release, whose peers are still the old ones, so that check, which
+   is not a required one, fails on the repin and on `main` until the release
+   pull request below.
+2. Run `pnpm sync:stack`, then `pnpm install` to update the lockfile.
+   `pnpm sync:stack` rewrites in place each disagreement above that is a
+   version, a range or a dist-tag; it reports anything else (`catalog:`,
+   `workspace:*`) for you to change by hand.
+3. Regenerate the checked-in modules with the new CLI: each example's and
+   `e2e/`'s `pnpm gen` (their `gen:check` fails until you do),
+   `packages/core/tests/fixtures/` (its README has the command),
+   `scripts/check-snippets/app/generated/` from the `.did` beside each module,
+   and `scripts/check-snippets/docs/guides/generated/`: `icp_ledger.ts` and
+   `ckbtc_minter.ts` are what `gen` writes for the icrc-ledger example's
+   `.did` cut down to the methods the guides show (each file's header says
+   how), and `accounts.ts` is Prettier's layout of the core fixture of that
+   name.
+4. Check what a release changes by hand. The prose that says what one release
+   does, such as "`@meantjs/cli` 0.5.0 reads ...", is left alone by
+   `pnpm sync:stack`; so is the hand-written copy of a generated `Actor` in
+   `packages/react/tests/suspense.test-d.tsx`. `pnpm test` runs the real CLI
+   and fails on the generated lines that
+   `packages/vite-plugin/tests/generation.test.ts` looks for.
+5. Run the gates, and name the Meant release in the pull request.
+
+A feature that needs the new release comes in a pull request after the repin.
+The release pull request that dates the changelog comes last, and soon after:
+it moves the examples to the new ic-reactor version, and the published-examples
+check then waits for its publish. Dependabot leaves `@meantjs/schema` and
+`@meantjs/cli` alone (`.github/dependabot.yml`): its bump would change one pin
+of many and fail `pnpm check:stack`, and a repin is chosen here.
+
+## Size budget
+
+`pnpm size` (the CI step "Check package sizes") runs size-limit over the built
+packages, gzipped. Every limit sits just above its measured size, on purpose:
+
+| Check                   | Config                                        | What it measures                                                             |
+| ----------------------- | --------------------------------------------- | ---------------------------------------------------------------------------- |
+| Core Library            | `packages/core/.size-limit.js`                | core's own `dist/index.js`                                                   |
+| React bindings          | `size-limit` in `packages/react/package.json` | react's own `dist/index.js`                                                  |
+| App: `{ createClient }` | `scripts/size-app/.size-limit.js`             | `createClient` with all it pulls from core's peers                           |
+| App: React path         | `scripts/size-app/.size-limit.js`             | `createClient`, `ReactorProvider` and `useClient`, with every peer but React |
+
+size-limit adds every `peerDependencies` entry of the package it runs in to
+each check's `ignore`, so the first two never see `@icp-sdk/core`,
+`@meantjs/schema`, `@noble/curves` or `@tanstack/query-core`. The last two
+run from `scripts/size-app/`, a private workspace package that declares no
+peers, so a change in what core pulls from them fails there. Keep it free of
+peers; `pnpm test:scripts` checks that.
+
+A pull request that changes any of these numbers says by how much, in bytes,
+and raises the limit it crosses in the same change; one that shrinks a number
+by more than 0.5 kB lowers that limit. Where the config has comments (core's
+and `scripts/size-app/`'s), they record the new measured size and margin. That
+includes a dependency bump that moves a peer's size. Read the numbers with `pnpm build && pnpm size`; run
+`pnpm exec size-limit --json` in `packages/core`, `packages/react` or
+`scripts/size-app` for exact bytes.
+
+## Code snippets
+
+`pnpm check:snippets` compiles every ` ```ts `, ` ```tsx ` and
+` ```typescript ` fence of `packages/*/llms.txt`, `skill-packages/**/*.md`
+(when a skill exists), `README.md` and `packages/*/README.md`, each as its own
+module, against the built packages. Agents copy these snippets into apps
+as they stand, so when one fails, fix the snippet: add the import it is
+missing, or update it to the current API.
+
+A snippet may use names its app would define without importing them: a
+canister's `./declarations/backend`, a `./reactor` module, a name built earlier
+on the page. Those come from `scripts/check-snippets/`: `app/` is the app every
+document shares, and a directory named in `CONTEXTS` in
+`scripts/check-snippets.mjs` holds what differs for one document. A relative
+import resolves to the module of the same path there, and `globals.ts` lists the
+names a snippet may use without importing. Add a missing app name there, never
+a library export: a snippet that uses one must import it. `app/` holds a few
+generic names and the generated modules the guide imports
+(`app/generated/icrc1.ts`, `app/generated/backend.ts`).
+
+The consumer guides (`packages/*/llms.txt` and `skill-packages/ic-reactor/`)
+get no globals, since an agent pastes them into
+an app that has none: each of their snippets imports or declares every name
+it uses. A relative import there resolves first to a snippet of the same
+guide (or skill) whose first line names that file, such as `// src/reactor.ts`
+for `./reactor`, so it is checked against the module the reader was shown.
+
+A fence that is not code to paste, such as a type signature or an interface
+restating a library type, opts out with `nocheck` after its language,
+` ```ts nocheck `, or with `// @snippet-skip` as its first line. Give a
+placeholder such as `...` a real value instead. `pnpm check:snippets --verbose`
+lists every snippet with its result.
+
+The docs site's hand-written pages (`docs/src/content/docs`, without the
+TypeDoc output in `libs/`) are gated too, by `pnpm check:snippets:docs`, which
+CI runs in the job that installs the examples. Unlike the guides, a docs page
+may assume the app it is about, so a page compiles against
+`scripts/check-snippets/docs/<section>/` (its directory under the docs content
+root, `root` for a page at the top), then against the default app. Put a name
+the page assumes there, such as the canister its examples call or a component
+the page only mentions. A fence that uses a library export still imports it,
+and a fixture never re-exports one. A library an example app installs is the
+real package once that example is listed in `DEPENDENCY_SOURCES`; the few
+installed nowhere are declared once, faithfully, in
+`scripts/check-snippets/ambient.d.ts`. An `@/` import resolves to a fixture
+at that path. The checker type-checks, and it fails a snippet that calls a hook
+(`useXxx(...)` or `query.useXxx()`) outside a component or a custom hook: at
+the top of the module, in a class, or in a function that is not capitalised or
+named `useXxx`. Wrap it in a component. A call that must fail to compile is shown with
+`// @ts-expect-error`. Rules it cannot see (no hand-written query keys, update
+methods only through mutations) are yours to keep when you write an example.
+
+## Pre-commit hooks
+
+This repo uses Husky + lint-staged. Hooks will be installed automatically when you run `pnpm install` (the `prepare` script runs `husky`). The `pre-commit` hook runs `lint-staged` to format and add staged files.
+
+If you need to re-install hooks manually:
+
+```bash
+pnpm prepare
+```
+
+## Troubleshooting
+
+### `Cannot find native binding` after a dependency bump
+
+A `node_modules` installed before a dependency bump and then updated in place
+can lose its link to a native optional package while the package itself stays
+on disk. Run `pnpm install` first. For satteri's binding, which the workspace
+hoists (see below), that is enough. If the error remains, the lost link is one
+a plain install does not recreate, with or without `--frozen-lockfile`. Relink
+every package instead:
+
+```bash
+pnpm install --force
+```
+
+If that is not enough, delete every `node_modules` in the workspace and
+install from scratch:
+
+```bash
+pnpm clean && pnpm install
+```
+
+The error blames an npm bug and tells you to delete `package-lock.json` and
+run `npm i` again. That text comes from the native package's loader. This repo
+uses pnpm and has no `package-lock.json`, so the advice does not apply.
+
+The Astro 7.3 bump did this to satteri's binding, and `pnpm docs:build` failed
+with `Cannot find module '@bruits/satteri-<platform>'` (issue #408).
+`pnpm-workspace.yaml` now hoists that binding to the root `node_modules`, so
+the docs build no longer depends on the lost link. A future bump can still
+strand a different native package the same way.
+
+### `pnpm verify:audit` and the ignored advisories
+
+`pnpm verify:audit` (the CI job "Audit") fails on any high or critical
+advisory in the workspace. Fix one by raising the dependency, or a `pnpm.overrides`
+entry in the root `package.json`, past the patched version. Only when no
+patched version exists, and the package is reachable only from tooling that
+never ships (the docs site's build, not `packages/*` or an example's runtime),
+may the advisory go in `pnpm.auditConfig.ignoreGhsas`, with its reason here.
+Remove an entry as soon as a patched version is released.
+
+| Advisory                                                                 | Package                                             | Reached through                                                                                                     | Why it is ignored                                                                                                                                                          |
+| ------------------------------------------------------------------------ | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [GHSA-ch52-4w7c-c8xp](https://github.com/advisories/GHSA-ch52-4w7c-c8xp) | `http-cache-semantics` ≤ 4.2.0 (no patched version) | `docs > astro`                                                                                                      | A shared HTTP cache can serve one user's response to another through `max-stale`. The docs site is built to static files in CI; it runs no shared cache that serves users. |
+| [GHSA-vfj7-8cjw-p6xm](https://github.com/advisories/GHSA-vfj7-8cjw-p6xm) | `braces` ≤ 3.0.3 (no patched version)               | `docs > remark-cli > unified-args > chokidar`, `docs > starlight-page-actions > vite-plugin-static-copy > chokidar` | A deeply nested pattern exhausts the stack. The patterns are the docs tooling's own file globs, not input from users.                                                      |
+
+## Publishing (trusted publishing / tokens)
+
+This repository enforces **OIDC Trusted Publishing** for releases (no long-lived publish tokens for the publish step). Trusted publishing is more secure and produces provenance attestations when used from GitHub Actions.
+
+- To enable: go to your package on npmjs.com → Settings → Trusted publishers and add this repository's workflow filename (e.g., `release.yml`).
+- `@ic-reactor/core`, `@ic-reactor/react` and `@ic-reactor/vite-plugin` trust `release.yml` (4.x from `main`, and core and react 3.x from `v3`), and so does `@ic-reactor/mcp` (4.x from `main`), once its name exists on npm (see [A package's first release](#a-packages-first-release)). Until the 3.x line's end, `@ic-reactor/vite-plugin` also trusts `release-tools.yml`, which publishes its 0.x security releases from `v3`; remove that publisher then.
+- Bind each trusted publisher to the `npm-release` environment, the environment of every publish job on `main` and `v3`; every publisher of the eight packages names it. A package can hold up to 10 publishers, and an entry without an environment still accepts any job of its workflow, even next to a bound one, so the binding holds only while no entry is left without it: a new entry names `npm-release` from the start, and an unbound one is never added back. npm expires a new entry that no publish uses within 2 days ([npm docs](https://docs.npmjs.com/trusted-publishers)), so add one right before the release that uses it. `npm-release` has no reviewer. With the same deployment tag policy as `npm-publish`, it lets npm refuse the publish job of an older commit, which has no environment (see "Tagging a 3.x release" below), and any job from a ref other than a release tag (see "Approving a release" below).
+- Ensure the publish job of `release.yml` has `permissions: id-token: write` (already configured). It is the only job that has it.
+- After enabling and validating Trusted Publishing, do not add a write `NPM_TOKEN` secret — publishing will use the OIDC token.
+
+If your CI needs to install private dependencies, create a **read-only** granular token on npmjs.com and store it as `NPM_READ_TOKEN` (the install step will use this token when present).
+
+On `main` the release lane publishes `@ic-reactor/core`, `@ic-reactor/react`, `@ic-reactor/vite-plugin` and `@ic-reactor/mcp` in lockstep from `v4.*` tags: the packages of `LANE_PACKAGES` in `scripts/release-tag.mjs`, which `release.yml` names in each of its lists. `scripts/release-tag.mjs` decides for both `scripts/release.js` and `release.yml`: a stable 4.x version publishes under the `latest` dist-tag and becomes the latest GitHub Release, a 4.x prerelease publishes under `beta`, and any other version (3.x, 5.x, not semver) is refused. `release.yml` also requires the tagged commit to be on `main`.
+
+The 3.x line releases from the `v3` branch with that branch's own workflows: `v3.*` tags publish `@ic-reactor/core` and `@ic-reactor/react` 3.x under the `v3-latest` dist-tag and `@ic-reactor/candid` under `latest` (it has no 4.x), and `tools-v*`/`parser-v*` tags publish `@ic-reactor/vite-plugin` 0.x under `v0-latest` and the parser, codegen and cli under `latest`. None of them moves `latest` of core, react or vite-plugin, or takes the GitHub "Latest" badge, as long as the tag is on a `v3` commit that contains those lanes.
+
+### Tagging a 3.x release
+
+A tag push runs the workflow file of the commit the tag points at, not the branch's current one. `main`'s history (and `v3`'s, up to the merge that added its lanes) holds 3.x commits whose `release.yml` and `release-tools.yml` publish any stable version under `latest`, and some of them carry a version that was never published (core, react and candid 3.0.5; codegen, cli and vite-plugin 0.15.0). A `v3.*`, `tools-v*` or `parser-v*` tag on such a commit runs that commit's workflow, and the older ones have no preflight and no approval job. Before you push a 3.x tag, check the commit it points at:
+
+```sh
+SHA=$(git rev-parse v3.13.1)   # or tools-v0.15.2, parser-v0.6.1
+git show "$SHA":.github/workflows/release.yml | grep -q v3-latest && echo "v3 lane"           # for a v3.* tag
+git show "$SHA":.github/workflows/release-tools.yml | grep -q v0-latest && echo "v0 lane"     # for a tools-v* or parser-v* tag
+```
+
+Push the tag only when the check prints its line. The `npm-release` environment closes this for good, since no package has a trusted publisher without it: the publish jobs of `release.yml` on `main` and of both lanes on `v3` run in it, and the publish jobs of older commits do not, so npm refuses their tokens.
+
+`v3` and `main` may carry a ruleset that requires pull requests. A 3.x release script's printed `git push origin v3` then works only for a maintainer on the ruleset's bypass list. Otherwise push the release commit to a branch, merge its pull request with a merge commit (a squash or rebase would leave the tagged commit off the branch, and the preflight refuses it), and push the tag after the merge. A 4.x release from `main` always goes this way (below).
+
+### Cutting a release
+
+Start from the latest `main`, on a branch of the release's own: `git fetch origin main && git switch -c release/v<version> origin/main`. Then `pnpm release <version>` (such as `pnpm release 4.0.1`) prepares the release on that branch and commits it as `chore: release v<version>`: it bumps the root manifest and the lane's packages (core, react, vite-plugin and mcp), regenerates `packages/core/src/version.ts`, syncs the AI-context files and the examples, and updates the lockfile. It takes no argument but the version, and it never pushes, tags or publishes. It then prints the rest, which goes through a pull request: add the release's `CHANGELOG.md` section (see [Changelog at release time](#changelog-at-release-time)), push the branch and open its pull request into `main`, and once that is merged, put an annotated tag `v<version>` on the merge commit (it prints a `git log` that finds it) and push that tag. The tag starts `release.yml`, which publishes after the approval below.
+
+### Approving a release
+
+Pushing a release tag no longer publishes unattended. The release workflow (`release.yml`; on `v3` there is also `release-tools.yml` for the 3.x tooling lane) runs an `Approve publish` job against the `npm-publish` environment, which requires a reviewer to approve the run once before any package is published; every package in the release then publishes on that single approval. Preflight still runs first, so by the time the run pauses the tag has been checked against its branch, the manifests, the build, the tests and `verify:packages`, and the tarballs to publish are packed from that build. The approval also waits for the push runs of `ci.yml` and `e2e.yml` on the tagged commit to succeed: a tag on a commit that CI failed, or that no push to `main` tested, publishes nothing. The publish job then publishes the four tarballs back to back, core first and mcp last, with nothing installed, built or tested in between; if it stops part-way, re-running its failed job skips the packages npm already has from the same tarballs and publishes the rest. Approve it from the run's page under Actions, or from the pending-deployments prompt on the workflow run. Approving completes the release unchanged; rejecting it publishes nothing. npm versions are immutable, so this is the last point at which a wrong release can be stopped rather than superseded.
+
+The environment lives in repository settings (Settings → Environments → `npm-publish`) and carries:
+
+- a required reviewer (self-approval allowed, so for a solo maintainer this is a confirmation step, not a second-person requirement);
+- a deployment tag policy limited to `v*`, `tools-v*` and `parser-v*`, so a run from any other ref cannot deploy to it at all.
+
+The publish job runs in a second environment, `npm-release`, which carries the same tag policy and no reviewer. Every trusted publisher names it (see the publishing section above), so npm accepts a token only from a job in it, and a run from any other ref cannot publish whatever its workflow file says: the approval is read from that file, but the tag policy and the binding are not.
+
+The `environment:` key is read from the tagged revision, like the preflight, so a tag pointing at a commit that predates it would skip the pause. The tag policy is settings-enforced, but it applies only to a job that names the environment, and such a commit names none: the `npm-release` binding of the trusted publishers is what refuses its publish. The `Release tags` ruleset, which limits who can create those tags, is the third leg; none of the three is sufficient alone.
+
+## Commits & PRs
+
+- Use clear, descriptive commit messages.
+- Prefer small, focused PRs.
+- Include tests where applicable.
+- State the size delta of `pnpm size` (or that there is none), and raise a
+  limit only deliberately, as [Size budget](#size-budget) says.
+- Add or update documentation for public API changes.
+- Record a change users will notice under `## Unreleased` in
+  [`CHANGELOG.md`](./CHANGELOG.md), in its package's Added, Changed,
+  Deprecated or Fixed list. A behaviour change gets a one-line migration hint.
+
+## Changelog at release time
+
+The release scripts do not edit `CHANGELOG.md`. Before tagging, move the
+entries of the packages being released from `## Unreleased` into a new section
+named after the release (for example `## core, react, vite-plugin 4.0.0-beta.1`). The GitHub release that
+the tag creates still generates its own notes from the merged pull requests.
+
+## Code style
+
+- We use Prettier for formatting. Run `pnpm format` before opening a PR if you need to format files manually.
+
+## AI-assisted contributions
+
+AI-assisted contributions are welcome, but contributors are responsible for correctness before opening a PR.
+
+- Prefer existing IC Reactor patterns over introducing new abstractions.
+- The 3.x runtime is gone from `main`. Do not copy 3.x patterns (`ClientManager`, `Reactor`, hook factories) from the `v3` branch; follow the guide in `packages/core/llms.txt`.
+- Validate generated or AI-written code with tests/examples whenever possible.
+- Update docs/examples when public API usage changes.
+
+Repository AI context:
+
+- `AGENTS.md` — task-to-source routing and verification commands (read this
+  first)
+- `CLAUDE.md` — Claude / Anthropic project context
+
+Consumer AI context (for apps that install the packages; keep repo paths,
+pnpm commands and CI notes out of it): `packages/core/llms.txt`, shipped in
+core's tarball and opening with an `Applies to` version line, and the one
+consumer skill, `skill-packages/ic-reactor/SKILL.md`, which points at it.
+
+## Adding a package
+
+To add a new package in the workspace, create a new folder under `packages/` and add it to the workspace if necessary. Follow existing package conventions for `package.json`, `tsconfig`, and build scripts. Mark it `"private": true` until it is meant to publish: the gates and the release lane skip a private package.
+
+A package that publishes joins the lane, and every gate that lists the lane's packages:
+
+- its directory in `LANE_PACKAGES` (`scripts/release-tag.mjs`), after the packages it depends on, and in each list of `release.yml` (`scripts/release-workflow.test.mjs` holds them to `LANE_PACKAGES`);
+- its entry points in `scripts/export-budget.mjs`, or, for a package that only installs a command, its `bin` under `COMMANDS`;
+- its page in `docs/src/content/docs/packages/`, which names its Node floor, in the sidebars of `docs/astro.config.mjs` and `b3pay-module.json`, and as its `homepage`;
+- its name in the `versionChecks` of `scripts/check-ai-context.js`.
+
+### A package's first release
+
+npm adds a trusted publisher only to a package that already exists ([`npm trust`](https://github.com/npm/cli/blob/latest/docs/lib/content/commands/npm-trust.md): "The package you're configuring must already exist on the npm registry"), and `release.yml` publishes with no token. So the owner reserves a new name once, by hand, before the first release that includes it:
+
+1. From an empty directory, publish a placeholder: a `package.json` with the package's name, version `0.0.0`, the MIT license and the repository, and a `README.md` that says the name is reserved for the package and that its releases come from `release.yml`. Run `npm publish --access public`, signed in with two-factor authentication.
+2. Within the two days before the release tag, add the trusted publisher: `release.yml` in `B3Pay/ic-reactor`, environment `npm-release`, on the package's settings page on npmjs.com, or with npm 11.15.0 or later: `npm trust github @ic-reactor/<name> --file release.yml --repo B3Pay/ic-reactor --env npm-release --allow-publish`.
+3. Once the release is out, deprecate the placeholder: `npm deprecate @ic-reactor/<name>@0.0.0 "A placeholder that reserved the name. Install a 4.x version."`
+
+The placeholder holds `latest` until the first stable release, so a first release that is a prerelease leaves `npm install @ic-reactor/<name>` installing it. If the trusted publisher is missing when the tag runs, the publish job stops at that package, after the packages before it have published: add the publisher and re-run the failed jobs, and the job skips what npm already has and publishes the rest.
+
+## Reporting issues
+
+Use the templates when creating issues. Fill out reproduction steps and environment details to help us triage faster.
+
+Thanks again — we appreciate your contribution! 🎉

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-2026 Behrad Deylami
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,3 @@
-# Temporary Holding Version
+# @ic-reactor/mcp
 
-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.
+This version only reserves the name. The MCP server is released from 4.x on by `release.yml` in [B3Pay/ic-reactor](https://github.com/B3Pay/ic-reactor).

package/SECURITY.md

@@ -0,0 +1,74 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+**Please do not open a public issue for a security vulnerability.**
+
+Report it privately through GitHub's private vulnerability reporting:
+
+1. Go to <https://github.com/B3Pay/ic-reactor/security/advisories/new>
+2. Describe the issue, the affected package and version, and how to reproduce it.
+
+If private reporting is unavailable, open a public issue containing only "security report — please provide a private contact" and no technical detail, and a maintainer will follow up with a private channel.
+
+We aim to acknowledge a report within 5 working days.
+
+## What to include
+
+The more of this you can provide, the faster a fix lands:
+
+- Which package and version (`@ic-reactor/core`, `@ic-reactor/react`, `@ic-reactor/vite-plugin`, or a 3.x package: `@ic-reactor/candid`, `@ic-reactor/parser`, `@ic-reactor/codegen`, `@ic-reactor/cli`)
+- A minimal reproduction — a config file, a `.did`, or a short script
+- What an attacker controls, and what they gain
+- Any known workaround
+
+## Supported versions
+
+| Package                                 | Line     | Supported                                          | Branch |
+| --------------------------------------- | -------- | -------------------------------------------------- | ------ |
+| `@ic-reactor/{core,react,vite-plugin}`  | `4.x`    | Yes                                                | `main` |
+| `@ic-reactor/{core,react,candid}`       | `3.x`    | Security fixes until 90 days after the 4.0 release | `v3`   |
+| `@ic-reactor/{codegen,cli,vite-plugin}` | `0.15.x` | Security fixes until 90 days after the 4.0 release | `v3`   |
+| `@ic-reactor/parser`                    | `0.6.x`  | Security fixes until 90 days after the 4.0 release | `v3`   |
+
+Fixes land on the latest minor of each supported line. Older minors are not backported. `@ic-reactor/candid`, `@ic-reactor/parser`, `@ic-reactor/codegen` and `@ic-reactor/cli` have no 4.x: ic-reactor 4 generates canister modules with `meant gen` instead, and their lines end with 3.x's. The 0.15 line of `@ic-reactor/vite-plugin` is the plugin of 3.x apps, which generates with `@ic-reactor/codegen`.
+
+## Threat model
+
+This section is ic-reactor 4's: `@ic-reactor/core`, `@ic-reactor/react` and `@ic-reactor/vite-plugin` 4.x. The 3.x packages' threat model is in the [`v3` branch's SECURITY.md](https://github.com/B3Pay/ic-reactor/blob/v3/SECURITY.md).
+
+ic-reactor 4 is a client library and a Vite plugin. Two boundaries matter, and they have different trust assumptions.
+
+### Runtime (`core`, `react`)
+
+These run in the user's browser or on their server. In scope:
+
+- Anything that serves one principal's canister data to another: the caller-scoped query keys, a sign-in or sign-out while a fetch runs, and one client per request on a server
+- Anything that weakens certificate verification, in particular which root key a client takes: mainnet's built-in key, a key given in `network`, or one fetched only from a local host
+- Anything that lets untrusted input choose which canister a call is routed to. Certificate verification does not cover this: a substituted canister ID names a real canister, whose responses verify against the real root key. That includes the `ic_env` cookie: core believes its canister IDs only on a local replica, on a canister's own `<id>.icp0.io` page, or with `allowEnvConfig: true`, and never takes its root key for a mainnet host
+- Anything that mishandles delegations or identity material
+- An error that says a write did not execute when it may have, so that resending it can execute it twice
+
+Out of scope:
+
+- A canister returning wrong data, unless the library presents it as verified
+- `@ic-reactor/core/testing`: its fake replica and test client are for tests, not for production
+
+Candid encoding and decoding are `@meantjs/schema`'s. Report a decoding bug, such as a hostile reply that decodes to the wrong value or crashes the decoder, to Meant through <https://github.com/B3Pay/Meant/security/advisories/new>.
+
+### Development and build (`vite-plugin`)
+
+The plugin runs in `vite dev`, `vite preview` and `vite build`. Its options come from the Vite config, which is code the developer runs, so they are trusted. A `.did` file, its name, and an interface fetched from a network are not. In scope:
+
+- **The generator.** The plugin runs `meant gen` from the app's `node_modules`, with the running Node binary, in a child process and not through a shell. Anything that makes it run another program, or turns a `.did` path into anything but an argument, is in scope.
+- **Live interfaces.** A missing `didFile` is written from the canister's `candid:service` metadata, read from certified state, and `verify: "live"` compares a `didFile` with it. Anything that writes or accepts an interface that does not verify against the network's root key, or writes outside the configured `didFile`, is in scope.
+- **The `ic_env` cookie and the `/api` proxy** under `vite dev` and `vite preview`. A cookie that names a canister the local network did not report for that name, for example after the network restarted, or a proxy that sends requests to a host other than the local network, is in scope.
+- **Generated files.** A `.did` file or a fetched interface that writes outside the configured `outDir`, or puts code into a generated module beyond the declarations it describes. `meant gen` writes the module, so the fix can be Meant's.
+
+Out of scope: a developer's own Vite config pointing `outDir` or `didFile` somewhere destructive.
+
+If you are unsure which project a bug belongs to, report it here, and we will move it.
+
+## Disclosure
+
+We will credit reporters who want it. If you plan to publish, please give us 90 days from acknowledgement, or until a fix ships — whichever comes first.