port(v4-next): feat(docs): autogenerate node JSON-RPC API reference (#22543) (#23046)

Backport of #22543 to `backport-to-v4-next-staging`.

Cherry-pick of the squash-merge commit (`6fd76de513`) applied cleanly
via `git cherry-pick` (the automatic backport workflow's `gh pr diff |
git apply --reject` had failed; switching to a real cherry-pick resolved
it without manual conflict edits).

## Files

- `docs/docs-operate/operators/reference/node-api-reference.md` —
regenerated reference
-
`docs/network_versioned_docs/version-v2.1.11-ignition/operators/reference/node-api-reference.md`
— regenerated versioned snapshot
-
`docs/scripts/node_api_reference_generation/generate_node_api_reference.{sh,ts}`
— new generation script
- `docs/package.json` — wires up the generator

## Verification

- `git cherry-pick 6fd76de` succeeded with auto-merge; working tree
clean afterwards.
- Reference paths (`docs/docs-operate/...`,
`docs/network_versioned_docs/version-v2.1.11-ignition/...`) exist on the
staging branch, so the generated files land in valid locations.

Original PR description: see #22543.

ClaudeBox log: https://claudebox.work/s/6b4f81c28ae8a770?run=1

Author: critesjosh

.claude/skills/release-network-docs/SKILL.md

@@ -21,12 +21,15 @@ self-identify its release type, ask the user to confirm.
 
 **This skill does NOT:**
 
-- Generate API docs (aztec-nr or TypeScript)
+- Generate developer API docs (aztec-nr or TypeScript)
 - Generate CLI reference docs
 - Update developer version config or cut developer versioned docs
 - Update migration notes
 - Require aztec CLI, nargo, or yarn-project build
 
+**This skill DOES** regenerate the Node JSON-RPC API reference for the
+versioned docs (see Step 5a).
+
 ## Usage
 
 ```
@@ -165,7 +168,29 @@ Ask the user if any content changes are needed in `docs/docs-operate/`:
 - Operator changelog updates (if not handled by `/updating-changelog`)
 
 If the user has content changes, apply them to the source files in
-`docs/docs-operate/`. If no content changes are needed, skip to Step 6.
+`docs/docs-operate/`. If no content changes are needed, skip to Step 5a.
+
+### Step 5a: Regenerate Node API Reference
+
+The Node JSON-RPC API reference is auto-generated from TypeScript source. It
+must be regenerated from the release tag's source files to ensure the versioned
+docs reflect the actual API at that release.
+
+```bash
+cd docs
+yarn generate:node-api-reference
+```
+
+This writes to `docs/docs-operate/operators/reference/node-api-reference.md`
+using the source files from the currently checked-out tag. The generator parses
+`yarn-project/stdlib/src/interfaces/aztec-node.ts` and
+`yarn-project/stdlib/src/interfaces/aztec-node-admin.ts` directly (no
+yarn-project build needed, but `yarn-project/node_modules/` must be installed
+so `npx tsx` can resolve `typescript` — run `yarn install` from `yarn-project`
+if needed).
+
+Verify the output lists the expected number of methods and has no ungrouped
+methods warnings.
 
 ### Step 6: Build and Validate
 
@@ -284,6 +309,10 @@ Check for stash conflicts. Then report to the user:
 - **No heavy prerequisites**: This skill does not require aztec CLI, nargo, or
   a yarn-project build. Only `yarn` (for the docs build), `curl`/`jq` (for
   the RPC query), and `cast` (for on-chain address queries) are needed.
+- **Node API reference is auto-generated**: Run `yarn generate:node-api-reference`
+  (Step 5a) before building. The generator parses TypeScript source directly, so
+  no yarn-project build is required — but `yarn-project/node_modules/` must exist
+  (run `yarn install` from `yarn-project` if missing).
 - **Build must pass**: Do not cut versioned docs until `yarn build` succeeds.
 - **COMMIT_TAG needs `v` prefix**: The preprocessor uses COMMIT_TAG for GitHub
   URLs and git tag references. Omitting the `v` will break links in versioned

docs/CLAUDE.md

@@ -29,6 +29,8 @@ This project uses Yarn 4.5.2 as specified in the `packageManager` field of packa
 - `yarn generate:typescript-api` - Generate TypeScript API docs (requires yarn-project to be built)
 - `yarn generate:typescript-api v3.0.0-devnet.6` - Generate for a specific version
 - `RELEASE_TYPE=mainnet yarn generate:typescript-api v4.2.0` - Generate with explicit release type
+- `yarn generate:node-api-reference` - Generate Node JSON-RPC API reference (requires yarn-project source files and yarn-project/node_modules; no build needed)
+- `yarn generate:node-api-reference --target-dir <dir>` - Generate into a specific versioned docs directory
 
 The `RELEASE_TYPE` env var overrides version string pattern matching for output folder selection. This is useful when the version string doesn't self-identify its release type.
 

docs/README.md

@@ -270,6 +270,44 @@ yarn generate:typescript-api v3.0.0-devnet.6
 
 The generated docs are linked from the [TypeScript API Reference](/developers/docs/aztec-js/typescript_api_reference) page.
 
+### Node JSON-RPC API Reference
+
+The Node JSON-RPC API reference is auto-generated from the TypeScript interface definitions and Zod schemas in `yarn-project/stdlib/src/interfaces/`. The generator parses the source AST to extract method names, JSDoc comments, and parameter/return types.
+
+**Source files:**
+
+- `yarn-project/stdlib/src/interfaces/aztec-node.ts` — `AztecNode` interface (`node_` methods)
+- `yarn-project/stdlib/src/interfaces/aztec-node-admin.ts` — `AztecNodeAdmin` interface (`nodeAdmin_` methods)
+- `yarn-project/stdlib/src/block/l2_block_source.ts` — `L2BlockSource` interface (JSDoc for inherited methods)
+
+**Prerequisites:** `yarn-project` must have `node_modules/` installed so `npx tsx` can resolve `typescript`. Run `yarn install` from `yarn-project` if needed. No build is required — the generator parses source `.ts` files via the TypeScript Compiler API, not compiled output.
+
+**Generate the reference doc:**
+
+```bash
+yarn generate:node-api-reference
+```
+
+This writes to `docs-operate/operators/reference/node-api-reference.md`.
+
+**Generate for a specific versioned docs directory:**
+
+```bash
+yarn generate:node-api-reference --target-dir network_versioned_docs/version-v4.1.3/operators/reference
+```
+
+**How it works:**
+
+1. Parses TypeScript interfaces with the TS Compiler API to extract JSDoc comments
+2. Parses Zod schema object literals from source AST to enumerate methods and extract types
+3. Generates markdown with method grouping, curl examples, and admin API security warnings
+
+**When to regenerate:**
+
+- When interface methods or Zod schemas change in `yarn-project/stdlib/src/interfaces/`
+- When cutting a new versioned snapshot of network docs (pass `--target-dir` to write into the versioned directory)
+- The source doc (`docs-operate/`) should be kept in sync with the latest code
+
 ## Macros
 
 As mentioned above, Aztec docs pull code from the source files. This makes it easy to include sections of the source code in tutorials and other examples.