chore: resync the production spec and document the two generators

[justinwlin]

Takes up the production spec (cursor pagination on the list endpoints, plus the account-secrets paths) and documents how this repo's generation relates to the MCP server's.

The spec and schema changes here are byte-identical to the daily automation branch (#3, open since Sept 18). I verified that with git diff origin/automation/production-spec — empty. Merging this makes that PR's diff disappear, and the automation closes a superseded update PR on its next run.

What the automation does not do is write a changeset, by design — it never versions or publishes. So #3 on its own lands types that never reach npm, and @runpod/typescript-api-sdk stays at 0.1.1 for consumers. This adds the minor changeset so the update can actually ship.

That matters right now: runpod-mcp pins this package and bundles it, and its hand-written list tools can't pass the new cursor/limit parameters until a published version carries the types.

The docs section (docs/development.md → "The other generator: runpod-mcp") explains the split — this repo generates types for the compiler, the MCP server generates tool definitions read at runtime by a language model — and that an upstream change is normally taken up twice, SDK first. Nothing documented that relationship in either repo, which is how a resync ends up looking complete while half a surface is stale.

What this unblocks

runpod/runpod-mcp#98 vendored the same spec and regenerated its tool surface, so its generated tools (list-pods, list-endpoint-releases, list-endpoint-builds) already paginate — they dispatch from the spec and never consult these types.

Its curated tools cannot. list-endpoints and list-templates are hand-written and call the typed client here, so passing cursor/limit or reading pagination.nextCursor fails tsc against the pinned 0.1.1.

So once this merges and is released to npm, the sequence there is: bump the pin, then teach those two handlers the new parameters. Merging this without a release does not unblock anything — which is why the changeset matters here more than the regenerated types.

Verification

scripts/sync_spec.py --check    Vendored spec matches normalized production OpenAPI.
scripts/generate.mjs --check    Generated schema is current.
pnpm typecheck                  clean
pnpm test                       61 passed, 1 skipped
node --test scripts/test_query_contract.mjs   pass

The regenerated schema carries nextCursor and hasNextPage, the cursor/limit query parameters on the paginated paths, and the five account-secret operations.

🤖 Generated with Claude Code

[lukepiette]

Approving. Verified locally on the branch:

• git diff origin/automation/production-spec is limited to the changeset and the docs section, so the spec and schema really are identical to #3.
• sync_spec.py --check, generate.mjs --check, pnpm typecheck, pnpm test (61 passed, 1 skipped), test_query_contract.mjs, and the Python spec tests all pass.
• The changeset's "additive" claim holds. Deleted lines in the spec diff are description rewrites and moved lines; ListPodsResponse and ListTemplatesResponse still exist, and the required lists only gain pagination.
• The runpod-mcp claims are accurate: the pin is exactly 0.1.1 under devDependencies and src/specgen/generated/tools.gen.ts exists.
• version.yml runs on push to main via changesets/action, so merging this opens a Version Packages PR. Publishing still needs that second merge.

Two non-blocking nits, one inline on the docs and one here:

The description says runpod/runpod-mcp#98 "vendored the same spec and regenerated its tool surface, so its generated tools already paginate." #98 is still open, so nothing there paginates yet. Worth rewording so the sequencing reads correctly for whoever picks this up later.

[lukepiette]

Nit: house style avoids em dashes in docs. Commas or a colon read the same here, e.g. "Everything around it (retries, deadlines, rate-limit metadata, the SSE iterator) is written by hand." Same applies at lines 86, 96, and 99.