docs: complete backport of #22543 with script improvements and skill updates

The original cherry-pick of 6fd76de carried only the first commit of
PR #22543's five-commit feature branch, leaving the script using the
pre-22543 build-required check and missing the SKILL.md/CLAUDE.md/README.md
documentation that landed alongside.

Bring this backport in line with PR #22543's final merged state:

- Replace the .sh `stdlib/dest/` build check with source-file + node_modules
  checks (no yarn-project build needed).
- Apply the .ts generator improvements: optional handling order, array
  parenthesization, BlockHash in BlockParameterSchema, JSDoc index fix,
  name-aware example params, remarks rendering, fallback warnings.
- Add Step 5a (Regenerate Node API Reference) to release-network-docs
  SKILL.md plus the matching Key Points entry.
- Document `yarn generate:node-api-reference` in docs/CLAUDE.md and add
  the Node JSON-RPC API Reference section to docs/README.md.
- Regenerate docs-operate/.../node-api-reference.md against this branch's
  yarn-project interfaces (64 methods, 55 node + 9 admin).

METHOD_GROUPS adjustments for this branch's API surface: re-add
getSlashPayloads to the admin group (still present in
aztec-node-admin.ts here) and drop getPredictedMinFees from the fees
group (not yet present here). The version-v2.1.11-ignition snapshot is
left untouched — its content reflects that release's API and would be
corrupted by regenerating against HEAD.

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.