@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/.github/workflows/release.yml

@@ -0,0 +1,326 @@
+name: Release
+
+# The 4.x release lane: @ic-reactor/core, @ic-reactor/react,
+# @ic-reactor/vite-plugin and @ic-reactor/mcp in lockstep, from main. Every
+# list of them below names the lane of scripts/release-tag.mjs
+# (LANE_PACKAGES), in its order; scripts/release-workflow.test.mjs checks
+# that. A stable 4.x tag publishes under npm's `latest` dist-tag and becomes
+# the latest GitHub Release; a 4.x prerelease publishes under `beta`
+# (scripts/release-tag.mjs decides, for this workflow and scripts/release.js
+# alike). A tag push runs the workflow file of the tagged commit, so 3.x tags
+# (`v3.*`, `tools-v*`, `parser-v*`) on the v3 branch run v3's own lanes, which
+# never touch `latest` for core, react or vite-plugin.
+on:
+  push:
+    tags:
+      - "v4.*"
+
+permissions:
+  contents: read
+
+concurrency:
+  # Keyed per tag, NOT per lane. A shared group serialises publishes, but GitHub
+  # keeps only ONE run pending per group: when a third run arrives, the run that
+  # was already waiting is cancelled outright, silently dropping a release.
+  group: release-${{ github.ref_name }}
+  cancel-in-progress: false
+
+jobs:
+  # Nothing verified the commit a tag points at: ci.yml and e2e.yml have no `tags:`
+  # trigger, so a tag could publish code that never passed a single check. This job
+  # gates the publish, and packs the tarballs it publishes.
+  preflight:
+    name: Preflight
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    outputs:
+      dist_tag: ${{ steps.tag.outputs.dist_tag }}
+      prerelease: ${{ steps.tag.outputs.prerelease }}
+      make_latest: ${{ steps.tag.outputs.make_latest }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version: 24
+
+      - name: Setup pnpm
+        run: |
+          corepack enable
+          corepack prepare pnpm@10.30.3 --activate
+
+      - name: Tag must be an ancestor of main
+        run: |
+          set -euo pipefail
+          git fetch --no-tags origin main
+          if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/main; then
+            echo "::error::$GITHUB_SHA is not an ancestor of origin/main. Refusing to publish."
+            exit 1
+          fi
+
+      # A 4.x version only: a stable one goes to `latest`, a prerelease to
+      # `beta`. Anything else (a 3.x or 5.x tag, a tag that is not semver)
+      # fails here, before the build, and publishes nothing.
+      - name: Tag must be a 4.x version
+        id: tag
+        run: |
+          set -euo pipefail
+          node scripts/release-tag.mjs "$GITHUB_REF_NAME" | tee -a "$GITHUB_OUTPUT"
+
+      - name: Tag version must match package manifests
+        env:
+          EXPECTED: ${{ steps.tag.outputs.version }}
+        run: |
+          set -euo pipefail
+          echo "Tag version: $EXPECTED"
+          for pkg in packages/core packages/react packages/vite-plugin packages/mcp; do
+            ACTUAL="$(node -p "require('./$pkg/package.json').version")"
+            if [ "$ACTUAL" != "$EXPECTED" ]; then
+              echo "::error::$pkg is at $ACTUAL but the tag says $EXPECTED."
+              exit 1
+            fi
+          done
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile --filter '!./examples/**'
+
+      - name: Build, type check and test
+        run: |
+          set -euo pipefail
+          pnpm build
+          pnpm typecheck
+          pnpm test
+
+      - name: Verify published artifacts
+        run: pnpm verify:packages
+
+      # The tarballs the publish job publishes, packed from the build this job
+      # just tested. Nothing is built or tested between here and the publish,
+      # so a test cannot fail half-way through a release, after core is out and
+      # before react is (#909). pnpm pack turns workspace:* into the version.
+      - name: Pack the release
+        run: |
+          set -euo pipefail
+          VERSION="${GITHUB_REF_NAME#v}"
+          mkdir -p "$RUNNER_TEMP/tarballs"
+          for name in core react vite-plugin mcp; do
+            (cd "packages/$name" && pnpm pack --pack-destination "$RUNNER_TEMP/tarballs")
+            if [ ! -s "$RUNNER_TEMP/tarballs/ic-reactor-$name-$VERSION.tgz" ]; then
+              echo "::error::pnpm pack made no ic-reactor-$name-$VERSION.tgz."
+              exit 1
+            fi
+          done
+          ls -l "$RUNNER_TEMP/tarballs"
+
+      - name: Upload the release tarballs
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: release-tarballs
+          path: ${{ runner.temp }}/tarballs/*.tgz
+          if-no-files-found: error
+          retention-days: 7
+
+  # ci.yml and e2e.yml never run for the tag itself. The tagged commit is the
+  # release pull request's merge into main, and that push ran both: this job
+  # waits for those two runs and fails unless both succeeded. That brings
+  # every gate they hold to the publish, beside preflight's own: lint, the
+  # export budget, the trap and fault checks, the snippets, the peer floors,
+  # the examples and the e2e suite (#909).
+  ci-passed:
+    name: CI passed on the tagged commit
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    permissions:
+      actions: read
+    steps:
+      - name: Wait for ci.yml and e2e.yml on the tagged commit
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          start=$(date +%s)
+          while :; do
+            waiting=""
+            missing=""
+            for workflow in ci.yml e2e.yml; do
+              # The newest run of the workflow for a push of this commit.
+              run="$(gh api "repos/$GITHUB_REPOSITORY/actions/workflows/$workflow/runs?head_sha=$GITHUB_SHA&event=push&per_page=1" \
+                --jq '.workflow_runs[0] | if . == null then "none" else "\(.status) \(.conclusion) \(.html_url)" end')"
+              read -r status conclusion url <<< "$run"
+              if [ "$status" = "none" ]; then
+                missing="$missing $workflow"
+              elif [ "$status" != "completed" ]; then
+                waiting="$waiting $workflow"
+              elif [ "$conclusion" != "success" ]; then
+                echo "::error::$workflow ended $conclusion on $GITHUB_SHA: $url. Re-run its failed jobs until it succeeds, then re-run the failed jobs of this run."
+                exit 1
+              else
+                echo "$workflow succeeded on $GITHUB_SHA: $url"
+              fi
+            done
+            if [ -z "$waiting$missing" ]; then
+              exit 0
+            fi
+            elapsed=$(( $(date +%s) - start ))
+            if [ -n "$missing" ] && [ "$elapsed" -ge 600 ]; then
+              echo "::error::No push run of$missing on $GITHUB_SHA after 10 minutes. Tag the merge commit of the release pull request, which a push to main tested."
+              exit 1
+            fi
+            if [ "$elapsed" -ge 3000 ]; then
+              echo "::error::Still running on $GITHUB_SHA after 50 minutes:$waiting$missing."
+              exit 1
+            fi
+            echo "Waiting for$waiting$missing on $GITHUB_SHA"
+            sleep 30
+          done
+
+  # One approval for the whole release. The `npm-publish` environment carries a
+  # required reviewer and a deployment tag policy (v*, tools-v*, parser-v*) in
+  # repo settings. Preflight gates correctness and the `Release tags` ruleset
+  # gates who can create the tag; this is the only gate on the publish itself.
+  # npm versions are immutable, so a wrong publish can only be superseded.
+  # Self-approval is allowed, so for a solo maintainer it is a confirmation
+  # step, not a second-person requirement. Like preflight, it is read from the
+  # tagged revision: the tag policy is the part that holds regardless.
+  #
+  # It is its own job rather than a key on `publish`, which runs in
+  # `npm-release` (below). It asks for approval only once preflight and CI
+  # have passed.
+  approve:
+    name: Approve publish
+    needs: [preflight, ci-passed]
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    environment: npm-publish
+    steps:
+      - name: Approved
+        run: echo "Publishing ${GITHUB_REF_NAME} was approved."
+
+  # The publish holds the OIDC token, so it does only that: no checkout, no
+  # install, no cache and no build, and the one package it installs is npm,
+  # pinned exactly. It publishes the tarballs preflight packed and tested,
+  # back to back, core first and mcp last, and stops at the first that
+  # fails. Run again (Re-run failed jobs), it publishes the same tarballs and
+  # skips one npm already has with the same integrity, so a release that
+  # stopped half-way is finished, not superseded (#909).
+  #
+  # `npm-release` has no reviewer, so it adds no prompt. It carries the same
+  # deployment tag policy as `npm-publish` (v*, tools-v*, parser-v*), and the
+  # trusted publishers of the lane's packages name it, so npm accepts
+  # an OIDC token only from a job in this environment, which only a release
+  # tag can reach. That holds where the approval above cannot: a run from any
+  # other ref cannot deploy here, whatever its workflow file says, and the
+  # publish job of an older commit names no environment (a tag runs the
+  # workflow file of the commit it points at, and main's history holds 3.x
+  # commits whose release.yml publishes a stable version under `latest`).
+  publish:
+    name: Publish to npm
+    needs: [preflight, ci-passed, approve]
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    environment: npm-release
+    permissions:
+      id-token: write
+    steps:
+      - name: Download the tarballs preflight tested
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: release-tarballs
+          path: tarballs
+
+      - name: Setup Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version: 24
+          registry-url: "https://registry.npmjs.org"
+
+      # Trusted publishing (OIDC) needs npm 11.5.1 or later.
+      - name: Install npm
+        run: npm install -g npm@11.21.0 && npm --version
+
+      - name: Publish core, react, vite-plugin and mcp
+        shell: bash
+        env:
+          # Decided once, by preflight (scripts/release-tag.mjs).
+          TAG: ${{ needs.preflight.outputs.dist_tag }}
+        run: |
+          set -euo pipefail
+          # Always an explicit --tag: an empty one would let npm fall back to
+          # `latest` for any version.
+          case "$TAG" in
+            latest | beta) echo "Publishing under the $TAG dist-tag." ;;
+            *)
+              echo "::error::Preflight gave no dist-tag ('$TAG'); refusing to publish."
+              exit 1
+              ;;
+          esac
+          VERSION="${GITHUB_REF_NAME#v}"
+          for name in core react vite-plugin mcp; do
+            if [ ! -s "tarballs/ic-reactor-$name-$VERSION.tgz" ]; then
+              echo "::error::tarballs/ic-reactor-$name-$VERSION.tgz is missing or empty; publishing nothing."
+              exit 1
+            fi
+          done
+          for name in core react vite-plugin mcp; do
+            # The leading ./ makes npm read a file: without it, npm reads
+            # `tarballs/<file>.tgz` as a GitHub repository and runs git.
+            TARBALL="./tarballs/ic-reactor-$name-$VERSION.tgz"
+            # npm's dist.integrity is the sha512 of the tarball it was given.
+            INTEGRITY="sha512-$(openssl dgst -sha512 -binary "$TARBALL" | base64 -w0)"
+            PUBLISHED="$(npm view "@ic-reactor/$name@$VERSION" dist.integrity 2>/dev/null || true)"
+            if [ "$PUBLISHED" = "$INTEGRITY" ]; then
+              echo "@ic-reactor/$name@$VERSION is already published from this tarball; skipping it."
+              continue
+            fi
+            if [ -n "$PUBLISHED" ]; then
+              echo "::error::@ic-reactor/$name@$VERSION is already published, from another tarball ($PUBLISHED, not $INTEGRITY)."
+              exit 1
+            fi
+            echo "Publishing $TARBALL"
+            npm publish "$TARBALL" --access public --tag "$TAG"
+          done
+
+  # The one job that can write to the repository, once every package is out:
+  # a stable tag's release is marked Latest only after the last of them has
+  # published too, never while one of them may still fail.
+  release-notes:
+    name: GitHub release
+    needs: [preflight, publish]
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+    steps:
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64 # v3
+        with:
+          generate_release_notes: true
+          draft: false
+          prerelease: ${{ needs.preflight.outputs.prerelease == 'true' }}
+          # The "Latest" badge goes to a stable 4.x release only, never to a
+          # prerelease (and v3's lanes set it to false).
+          make_latest: ${{ needs.preflight.outputs.make_latest }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  # The examples against the packages this run just published, from the tagged
+  # commit: the green run of examples-published.yml that counts for a release.
+  # The release PR's own run of that workflow, and the push that merges it,
+  # defer while the examples pin only this unpublished version (awaitsRelease
+  # in scripts/test-examples-published.mjs): this run is the one that tests them.
+  # The publish job publishes every package of the lane before it ends, and
+  # --wait-for waits for each one the examples install, not only core.
+  # The script tests the dist-tag the tag's version publishes under: `beta`
+  # for a prerelease, `latest` for a stable version.
+  examples-published:
+    name: Examples on the published packages
+    needs: publish
+    permissions:
+      contents: read
+    uses: ./.github/workflows/examples-published.yml
+    with:
+      wait-for: ${{ github.ref_name }}

package/.husky/pre-commit

@@ -0,0 +1,12 @@
+#!/bin/sh
+
+# Format staged files and run lint-staged
+if command -v pnpm >/dev/null 2>&1; then
+  pnpm -s exec -- lint-staged
+elif command -v corepack >/dev/null 2>&1; then
+  corepack pnpm -s exec -- lint-staged
+else
+  echo "Error: pnpm not found in PATH (and corepack unavailable)." >&2
+  echo "Install pnpm or run commits from a shell where pnpm is available." >&2
+  exit 1
+fi

package/.prettierignore

@@ -0,0 +1,109 @@
+node_modules/
+dist/
+build/
+coverage/
+.docs/
+.docusaurus/
+.cache/
+**/dist
+**/target
+docs/dist
+.e2e/
+docs/public/
+.husky/
+.pnpm-debug.log
+.env
+.env.*
+
+# Generated by `next build` on every run, and it says so at the top. Prettier
+# strips the semicolons Next writes, so formatting it means a one-line diff
+# after every build.
+**/next-env.d.ts
+
+# `pnpm format:check` now walks the whole repo, and Prettier reads only the root
+# .gitignore plus this file -- never a nested .gitignore. Every build directory
+# that only a nested .gitignore covers has to be repeated here, or the check
+# fails in any working tree that has been built: `.next/` and `examples/*/out/`
+# alone accounted for 205 of the 249 files a repo-wide check flagged.
+.next/
+examples/*/out/
+dist-ssr/
+.tanstack/
+.nitro/
+.wrangler/
+.yarn/
+canister_ids.json
+
+# Editor state. Listed in several nested .gitignore files, which Prettier does
+# not read, so an untracked settings file would otherwise be rewritten in place.
+.vscode/
+.idea/
+
+# Claude Code worktrees and machine-local settings. Not covered by the root
+# .gitignore, so a repo-wide walk would format files on other agents' branches.
+.claude/
+
+# TypeDoc output, rewritten by `pnpm docs:build`. Also in the root .gitignore;
+# repeated here so the Prettier set does not silently depend on it.
+docs/src/content/docs/libs/
+
+# Rewritten by the TanStack Router plugin on every dev/build run; its own header
+# tells you to exclude it from linters and formatters.
+examples/canister-studio/src/routeTree.gen.ts
+
+# pnpm rewrites the lockfile on every install.
+pnpm-lock.yaml
+
+# evals/: inputs kept byte-identical to what produced them (evals/setup.mjs
+# regenerates them) — candid-core-cli output, the docs copied from the published
+# @candid-core and @ic-reactor packages, the vendored fake replica — plus
+# agent-run results.
+evals/conditions/*/starter/src/generated/icrc1.ts
+evals/conditions/*/docs/
+evals/harness/public/support/fake-replica.js
+evals/runs/
+# The pilots' aggregated results, kept byte for byte as evals/drive.mjs wrote
+# them: they are the record PREREGISTRATION.md cites.
+evals/results/
+
+# packages/core/tests/fixtures/: modules and a Contract envelope written by
+# `meant gen`, kept byte for byte (see the README there).
+packages/core/tests/fixtures/*.ts
+packages/core/tests/fixtures/*.envelope.json
+
+# scripts/check-snippets/app/generated/: the modules `meant gen` writes
+# for the `.did` files next to them, kept byte for byte. They are what a guide
+# snippet's `./generated/<name>` import resolves to.
+scripts/check-snippets/app/generated/*.ts
+
+# The modules and Contract envelopes `meant gen` (run by
+# @ic-reactor/vite-plugin or an example's `gen` script) writes from an example's
+# .did, kept byte for byte so that `gen:check` passes. Listed by name, not by a
+# glob over src/canisters/: a hand-written module put next to them (a stable
+# index.ts) must still be formatted and checked. Each example adds its own.
+examples/icrc-ledger/src/canisters/icrc1.ts
+examples/icrc-ledger/src/canisters/icrc1.envelope.json
+examples/icrc-ledger/src/canisters/icp_ledger.ts
+examples/icrc-ledger/src/canisters/icp_ledger.envelope.json
+examples/icrc-ledger/src/canisters/ckbtc_minter.ts
+examples/icrc-ledger/src/canisters/ckbtc_minter.envelope.json
+examples/next-ssr/src/canisters/icrc1.ts
+examples/next-ssr/src/canisters/icrc1.envelope.json
+examples/vite-wallet/src/canisters/backend.ts
+examples/vite-wallet/src/canisters/backend.envelope.json
+examples/vite-wallet/src/canisters/ledger.ts
+examples/vite-wallet/src/canisters/ledger.envelope.json
+examples/node-agent-tool/src/canisters/icrc1.ts
+examples/node-agent-tool/src/canisters/icrc1.envelope.json
+examples/canister-studio/src/canisters/icrc1.ts
+examples/canister-studio/src/canisters/icrc1.envelope.json
+examples/canister-studio/src/canisters/icp_ledger.ts
+examples/canister-studio/src/canisters/icp_ledger.envelope.json
+examples/canister-studio/src/canisters/ckbtc_minter.ts
+examples/canister-studio/src/canisters/ckbtc_minter.envelope.json
+
+# e2e/src/declarations/: the module and Contract envelope `meant gen`
+# writes from e2e/src/actor/hello_actor.did (`pnpm gen` in e2e/), kept byte for
+# byte so that `pnpm gen:check` passes.
+e2e/src/declarations/hello_actor.ts
+e2e/src/declarations/hello_actor.envelope.json

package/.prettierrc

@@ -0,0 +1,6 @@
+{
+  "singleQuote": false,
+  "semi": false,
+  "trailingComma": "es5",
+  "tabWidth": 2
+}

package/AGENTS.md

@@ -0,0 +1,103 @@
+# AGENTS.md instructions for @ic-reactor
+
+## Project snapshot
+
+This is `main`, the line of ic-reactor 4. `v3` is the 3.x line and takes
+security fixes only, until 90 days after the 4.0 release. Open pull requests
+for ic-reactor 4 against `main`, and 3.x security fixes against `v3`.
+
+ic-reactor 4 is a thin layer over a module that `meant gen` generates, plus one
+consumer guide. Its packages are written against the published stable Meant
+releases, `@meantjs/schema` and `@meantjs/cli`, each pinned exactly.
+
+### Packages
+
+- `@ic-reactor/core` (`packages/core`, `4.1.1`) — the 4 API of milestone 1: `createClient`, `ReactorError` and `isReactorError`, `parseUnits` and `formatUnits`, and their types (13 names, `scripts/export-budget.mjs`). `src/testing/` is the `@ic-reactor/core/testing` entry: `createTestClient` (a real client over the fake replica, with typed `TestHandlers` and a controllable sign-in) is its only export; the fake replica and the test auth behind it are internal.
+- `@ic-reactor/react` (`packages/react`, `4.1.1`) — `'use client'` bindings over a core client: `ReactorProvider`, `useClient`, `useAuth` and the type `ReactorProviderProps`. It never re-exports core.
+- `@ic-reactor/vite-plugin` (`packages/vite-plugin`, `4.1.1`) — generates the module by running `@meantjs/cli` (`meant gen`) 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 that gives an AI agent any canister's methods as tools and sends an update only after the person approves the exact call in the MCP client's form. It exports nothing to import (`COMMANDS` in `scripts/export-budget.mjs`).
+
+`@ic-reactor/parser`, `@ic-reactor/codegen`, `@ic-reactor/cli` and
+`@ic-reactor/candid` are not in this tree (the last stays at 3.x on `v3`).
+
+## Where to start for a task
+
+| Task                          | Start here                                                                                  |
+| ----------------------------- | ------------------------------------------------------------------------------------------- |
+| Core runtime                  | `packages/core/src/`, `packages/core/tests/`                                                |
+| React bindings                | `packages/react/src/`, `packages/react/tests/`                                              |
+| Vite plugin generation        | `packages/vite-plugin/src/generate.ts`, `src/index.ts`                                      |
+| `ic_env` cookie and dev proxy | `packages/vite-plugin/src/dev-environment.ts`, `src/env.ts`, `src/index.ts`                 |
+| MCP server                    | `packages/mcp/src/server/` (tools, approval), `src/interface/` (loader), `src/candid/`      |
+| Test client, fake replica     | `packages/core/src/testing/` (`test-client.ts` is the entry's only export)                  |
+| Real-replica e2e              | `e2e/` (Rust `hello_actor` canister, `e2e/test.sh`)                                         |
+| Example apps                  | `examples/<name>/` (own tests and `gen:check`; a page in `docs/src/content/docs/examples/`) |
+| Docs site (`/v4/`)            | `docs/`, `.github/workflows/docs.yml`, `scripts/assemble-docs-site.mjs`                     |
+| Docs on b3pay.net             | `b3pay-module.json`, `.github/workflows/b3pay-site.yml`, `docs/scripts/b3pay-static.mjs`    |
+| Consumer guide and skill      | `packages/core/llms.txt`, `skill-packages/ic-reactor/SKILL.md`                              |
+| Release lane                  | `scripts/release.js`, `scripts/release-tag.mjs`, `.github/workflows/release.yml`            |
+| Meant pins                    | `stack.json`, `scripts/check-stack.mjs`                                                     |
+| CI gates and their tests      | `scripts/` (`check-exports.mjs`, `verify-traps.mjs`, `verify-faults.mjs`)                   |
+
+## Verification commands
+
+- Build and test: `pnpm build`, `pnpm test`
+- Type check (CI gate): `pnpm typecheck` — each package's `typecheck` script plus `e2e/`'s.
+- Lint (CI gate): `pnpm lint`. Run `pnpm build` first: the type-aware rules read core's emitted `.d.ts`.
+- Format (CI gate): `pnpm format:check`
+- AI context (CI gate): `pnpm check:ai-context` — version stamps, and docs links limited to the published bases (`/v2/`, `/v3/`, `/v4/`), with `/v4/` links resolved against `docs/src/content/docs/`.
+- Stack pins (CI gate): `pnpm check:stack` — each Meant pin in a tracked `package.json`, each `@meantjs/<name>@<version>` in a `package.json` value or a `.md`, `.mdx` or `.txt` file, each docs peer-table row that says exactly `<version>`, and the two pins in code (`MEANT_CLI_VERSION`, the export budget's schema pin) must be exactly the version `stack.json` gives, outside the changelogs and the manifest's `frozen` paths; each listed package must be pinned by some `package.json` outside them, and each frozen path must hold a tracked file. Other files (`.ts`, `.yml`) are not read. A repin changes `stack.json`, moves the examples with the rest of the tree, and runs `pnpm sync:stack` (CONTRIBUTING.md, "The Meant pins"); prose that says what one release does is checked by hand.
+- Snippets (CI gate; build first): `pnpm check:snippets`, and `pnpm check:snippets:docs` for the docs pages.
+- Size (CI gate; build first): `pnpm size` — gzipped size-limit checks, each limit just above its measured size. `packages/core/.size-limit.js` and react's `size-limit` field measure each package's own code: size-limit leaves out every peer of the package it runs in. `scripts/size-app/` (a private workspace package that declares no peers, so nothing is left out) measures what an app pays with the peers included: `{ createClient }` from core, and `createClient` with `ReactorProvider` and `useClient` without React itself. A change that moves a number, a dependency bump included, states the delta in its pull request and raises that limit in the same change.
+- Published artifacts: `pnpm verify:packages`
+- Examples on the published packages: `pnpm test:examples:published` (needs only Node, npm and git) — each example's tracked files copied outside the repository and installed from npm with npm; it refuses a `workspace:` range, checks every installed @ic-reactor/* package is a real directory at the version of one npm dist-tag (with `--wait-for <version>`, as `release.yml` runs it after publishing, the tag that version publishes under; otherwise the tag of the branch's version in `packages/core/package.json`: `beta` for a prerelease and `latest` for a stable version), then runs the example's `typecheck`, `test` and `build` scripts, and its `.stackblitzrc` start command under a model of what StackBlitz's WebContainer lacks (no global `Iterator`; an `AsyncLocalStorage` that keeps no store across an await). Its own workflow, `.github/workflows/examples-published.yml`, runs it on pushes and pull requests to `main`. An example change that needs an unpublished API lands with the release that publishes it. A run without `--wait-for` whose examples all pin `^<the branch's own version>` while npm has no such version yet (a release pull request, or its merge before the tag), and no dependency uses a local protocol, runs the checks that need no registry (tracked config files, required scripts, and the `.stackblitzrc` start command, which must be a plain npm script command, `npm run <script>` with arguments after a bare `--`, naming a defined script), then defers to the release's run and passes, saying so; once that version is published, the same run tests its dist-tag.
+- Peer and TypeScript floors (CI gate; build first): `pnpm verify:peer-floors`
+- Docs: `pnpm docs:build`, `pnpm docs:check-links`. The site links to Candid Core's pages at `/candid-core/`, built from B3Pay/Meant (`node website/build.mjs`); with `CANDID_CORE_SITE` set to that build's `website/dist`, the link check checks the links into it and crawls its pages, as CI does. Without it those links are skipped, and in CI the check fails. `.github/workflows/docs.yml` deploys ic-reactor.b3pay.net, which keeps the 3.x and 2.x docs: each page there under `/v4/` and `/candid-core/` sends readers to the same page on b3pay.net (`/docs/ic-reactor/`, `/docs/meant/`), and the deploy stops when b3pay.net does not serve IC Reactor's docs, with the API reference, or Meant's.
+- Docs on b3pay.net: the same pages, the API reference and `packages/core/llms.txt` are a module of b3pay.net, served at `/docs/ic-reactor/`, as `b3pay-module.json` describes. Its sidebar is kept by hand beside the one in `docs/astro.config.mjs`: a page added to one goes in the other, and so does a new folder of the API reference, such as `libs/classes` for a first class (b3pay.net fails a listed folder that has no pages). The `Docs on b3pay.net` workflow builds and checks the module with b3pay.net's reusable workflow and builds that site with it, warning about a page missing from the sidebar and failing on a link that breaks there; on `main` it commits the module to the `b3pay-site` branch, which b3pay.net serves. Locally, from a b3pay.net checkout, after `pnpm -C docs run api` here: `npm run module:build -- --source ../ic-reactor --out ../ic-reactor-module`.
+- Export budget (CI gate; build first): `pnpm check:exports` — the built declarations of core, `core/testing`, react and the Vite plugin against the plan in `scripts/export-budget.mjs`: no unplanned name, no more than the cap, no name exported twice or also exported by `@meantjs/schema` or TanStack Query (D35), no `exports` subpath or publishable package the file does not list, and the schema declared only at the pinned version. Adding a public name or subpath means adding it to that file in the same change.
+- Trap types (CI gate): `pnpm verify:traps` — every `@ts-expect-error` of `packages/core/tests/traps.test-d.ts` must be reported as unused (TS2578) once its fault fixture in `scripts/traps/` removes it. How to add a trap is in that file's header.
+- Fault-proof runtime tests (CI gate): `pnpm verify:faults` — every test listed in `scripts/faults.json` must fail with its fault applied to a copy of its package. A test that guards a regression somebody could reintroduce gets an entry.
+- Script tests (CI gate; build first): `pnpm test:scripts` — the gates above, `check:ai-context` and `check:snippets`, each run against repositories built for the purpose.
+- A bug fix: `pnpm verify:test-fails <test file> --package <pkg>` on the new test, and a `scripts/faults.json` entry if it should stay proven
+
+## Generated files
+
+Outputs under `dist`, `.icp`, `target`, `.astro` and `*.tsbuildinfo` are build
+artifacts. `docs/src/content/docs/libs/` is TypeDoc output written by
+`pnpm docs:build`, or by `pnpm -C docs run api` alone, each file named in
+lowercase as its route is. `e2e/src/declarations/` is committed: the module
+`meant gen` writes from `e2e/src/actor/hello_actor.did` (`pnpm gen` in
+`e2e/`; `e2e/test.sh` fails a stale copy with `pnpm gen:check`).
+
+## AI context files
+
+`scripts/ai-context-files.js` lists them: `packages/core/llms.txt`, this file
+and `CLAUDE.md`, plus `packages/react/llms.txt` (a pointer to the guide) and
+the consumer skill `skill-packages/ic-reactor/`. The consumer guide is
+`packages/core/llms.txt`, shipped in core's tarball; it opens with an
+`Applies to` line naming core's version. Keep repo paths and contributor
+workflow out of it, and keep it free of the eval's hidden-test names and
+literals (`node evals/harness/check-docs.mjs "$PWD/packages/core/llms.txt"`).
+Its snippets import the generated modules in
+`scripts/check-snippets/app/generated/`.
+
+`check:ai-context` also fails on any of the 34 removed 3.x names
+(`scripts/removed-v3-names.js`) outside a section headed "Removed in 4.0", and
+`check:snippets` compiles every `ts`/`tsx` fence of these files against the
+built packages.
+
+Every skill under `skill-packages/` is one an app installs, so a contributor
+skill does not go there. `check:ai-context` wants its `SKILL.md` to list
+`@ic-reactor/react`'s version, and any other package's it lists, at the
+current version (`` - `@ic-reactor/react`: `<version>` ``), and its `SKILL.md`
+and `references/` to name no path that exists only in this repository
+(`packages/`, `examples/`, `scripts/` and the like).
+
+The hand-written docs pages (`docs/src/content/docs/`, not `libs/`) are not
+AI-context files, but `check:ai-context` holds them to the removed-names rule
+too, lets only `migrating-from-3.mdx` link `/v3/`, refuses an `@ic-reactor`
+version on a page (the site follows the branch) and any prerelease version
+that is not an exact pin of a `packages/*/package.json`, and wants each
+package's `homepage` to be its page under `/v4/packages/`.
+`pnpm check:snippets:docs` compiles the pages' fences; their fixtures are in
+`scripts/check-snippets/docs/<section>/`.