Sdk api reference

.claude/launch.json

@@ -0,0 +1,15 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "mint-dev",
+      "runtimeExecutable": "npx",
+      "runtimeArgs": [
+        "mint",
+        "dev"
+      ],
+      "port": 3000,
+      "autoPort": true
+    }
+  ]
+}

.claude/skills/release-version/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: release-version
+description: Use when releasing a new docs version for a product, freezing next to latest, or running the versioning scripts. Covers the ordered pre-freeze checks, the freeze itself, and the docs.json edits it does not do for you.
+---
+
+# Releasing a New Version
+
+When a product is ready to release, complete these steps in order.
+
+### 0. Optional pre-flight (SDK, up to a week ahead)
+
+Before committing to a freeze date, check how far the API reference has drifted from upstream without touching anything:
+
+```bash
+cd scripts/api-reference && npm run release-check -- --version next --dry-run
+```
+
+This copies the generated pages and `docs.json` aside, regenerates them in place, reports what would change, then restores them from the copy, so the working tree ends where it started. It is not read-only while it runs: commit or stash uncommitted work under `sdk/<version>/api-reference` or `docs.json` first, because a run killed outright leaves the only copy in the scratch directory it prints on startup. Run it a week or so before a planned freeze so drift is discovered while there is still time to investigate it, not on release day when the only options are to fix it under pressure or ship it anyway.
+
+### 1. Update the Changelog
+
+Update the changelog in `next/` first, so it carries over when the freeze copies `next/` to `latest/`. If the new version is still listed as `## Unreleased` in the upstream `CHANGELOG.md`, use `--unreleased-as` to label it correctly.
+
+```bash
+# If the version is released in CHANGELOG.md
+cd scripts/versioning && npm run changelogs -- --product <product> --target next --source <tag> --current-only
+
+# If the version is still listed as Unreleased in CHANGELOG.md
+cd scripts/versioning && npm run changelogs -- --product <product> --target next --source <tag> --unreleased-as <version> --current-only
+```
+
+### 2. Update Version-Pinned Content in `next/`
+
+Do this before freezing, not after. The freeze copies `next/` to `latest/`, so anything fixed in `next/` first lands in both directories in one pass. Fixing it afterwards means editing `latest/` and then syncing every file back to `next/`.
+
+Two things are version-pinned and do not follow the freeze on their own:
+
+**Version label in front matter (SDK only).** Five pages render the version under the page title via their `description`:
+
+```bash
+grep -rn 'description: "Version: v' sdk/next --include='*.mdx'
+```
+
+**GitHub links pinned to the previous release branch.** Pages link into the product repo at `release/v0.<N>.x` (SDK) or `v0.<N>.x` (CometBFT), and those refs keep pointing at the old version. Use the checker rather than a find-and-replace:
+
+```bash
+node scripts/versioning/check-github-refs.js --product <product> --targets next --json /tmp/flags.json
+```
+
+Review the report, then apply the safe rewrites with `--fix`. It bumps only what it can prove is safe and flags the rest.
+
+Do not blind-replace these by hand. Pinned tags and commit SHAs are deliberate historical citations, and bumping a ref under a `#L` line anchor can leave the link working while pointing at unrelated code. See the GitHub link section in [`scripts/versioning/CLAUDE.md`](../../../scripts/versioning/CLAUDE.md) for the rules and the measured failure rates.
+
+Hand the `--json` output to the [`update-stale-refs`](../update-stale-refs/SKILL.md) skill, which decides whether a flagged link means the page's prose needs a correction.
+
+A stale ref is often a symptom rather than the problem. A link that 404s at its current ref usually means the prose describes something upstream deleted, so check what the page claims before repointing the URL.
+
+### 2b. Regenerate and gate the API Reference (SDK only)
+
+The SDK API reference is generated from upstream protos at a resolved commit. Regenerate before freezing rather than after, for the same reason as step 2: the freeze changes which ref `latest` points at, and fixing content in `next/` first lands it in both directories in one pass.
+
+There is no scheduled regeneration any more, so this step is the only mechanism that keeps the reference current. If you remember a weekly workflow opening regeneration PRs, that is gone: docs versions freeze at release and published `latest` must not change between releases, and a cron cheap enough to run weekly can only report that upstream moved, which carries no decision attached. See [`scripts/api-reference/DESIGN.md`](../../../scripts/api-reference/DESIGN.md) for the fuller reasoning.
+
+```bash
+cd scripts/api-reference && npm run release-check -- --version next --ref release/v0.<N>.x
+```
+
+Pass `--ref` pointing at the release branch. Without it, `next` resolves to `main`, and a freeze taken from that regeneration publishes development content under the release's version number, which is the bug this gate exists to catch.
+
+`release-check` regenerates, runs the offline checks, builds `simd` from the exact commit the pages record, starts a chain on its own ports, and runs every documented query and transaction message against it. This is a blocking gate: a freeze does not proceed while it fails. Needs Go, Node, git, `schemathesis`, and `GITHUB_TOKEN` in the environment (`export GITHUB_TOKEN=$(gh auth token)`); it says which are missing before it builds anything.
+
+If generation fails, a guard has fired: a fact that cannot be derived from the protos needs writing by hand, and the error names the exact item. See [`scripts/api-reference/CLAUDE.md`](../../../scripts/api-reference/CLAUDE.md).
+
+### 2c. Read the generated prose (SDK only)
+
+The gate proves that what a page tells a reader to send is accepted by a chain. Nothing in it reads the page as English, so a field can carry a correct type, a working example, and a description that is a fragment, a typo, or advice contradicting the page above it.
+
+Use the [`review-generated-prose`](../review-generated-prose/SKILL.md) skill on the regenerated pages. It is the last step before the freeze, because the freeze copies whatever is in `next/` into `latest/` and publishes it.
+
+The one thing to know before starting: never edit a generated page. Every `.mdx` under `api-reference/grpc/` is overwritten on the next run, so a fix belongs either in `lib/render.js`, where the generator's own wording lives, or upstream in the proto comments a description came from. The skill covers how to tell which.
+
+### 3. Freeze the Version
+
+Run the freeze script from `scripts/versioning/`. This promotes `next/` to `latest/`, rewrites all internal links, injects `noindex` into `next/` pages, and updates `versions.json`.
+
+```bash
+cd scripts/versioning
+NON_INTERACTIVE=1 SUBDIR=<product> NEW_DISPLAY_VERSION=<version> npm run freeze
+```
+
+Then manually update `docs.json` for the product's dropdown:
+
+- Add a new version entry cloned from `next/`, with all paths rewritten from `<product>/next/` to `<product>/latest/`
+- Set `"tag": "Latest"` and `"default": true` on the `latest/` entry
+- Set `"tag": "Unreleased"` on the `next/` entry
+- Order: `latest` first, then `next`, then archived versions newest-first
+
+If the product has pre-existing archived version directories (e.g. `v0.53/`, `v10.1.x/`), tag them with `noindex` and `canonical`:
+
+```bash
+node tag-archived.js --product <product> --all
+```
+
+### 4. Check for Broken Links
+
+```bash
+npx mint broken-links
+```
+
+Fix any broken links before committing. Note that this checks internal page paths only. It does not validate heading anchors and it does not check external URLs, so nothing here catches a dead or misdirected GitHub link.

.claude/skills/review-generated-prose/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: review-generated-prose
+description: Use after regenerating the SDK API reference, as the last step before a freeze, to read the generated pages for grammar, spelling, house style, and whether they make sense to a reader. Also use when a generated page reads badly and it is unclear whether the fix belongs in the generator or upstream.
+---
+
+# Reviewing generated prose
+
+The checks around the API reference prove that what a page tells a reader to send is accepted by a chain. Nothing in them reads the page as English. A field can carry a correct type, a correct encoding note, a working example, and a description that is a sentence fragment, a typo, or advice that contradicts the page above it.
+
+This is the last step of a regeneration, after `npm run release-check` passes and before the freeze.
+
+## The rule that shapes everything here
+
+Never edit a generated page.
+
+`sdk/<version>/api-reference/grpc/*.mdx` and `rest/openapi.yaml` are overwritten wholesale on the next run. An edit to one is not a fix, it is a change that disappears silently at the next regeneration and takes its reviewer's attention with it.
+
+So every finding resolves to one of three places, and deciding which is the substance of this review:
+
+| The problem is in | Fix it in | How you can tell |
+| --- | --- | --- |
+| Wording the generator supplies: headings, table captions, encoding notes, the transaction envelope prose | `scripts/api-reference/lib/render.js` | The same phrasing appears on many pages, identically |
+| A field or method description | Upstream, as an issue or PR against `cosmos/cosmos-sdk` proto comments | The text appears once, and reads like a developer's comment |
+| One of the three hand-written pages | The page itself, which is safe to edit | `api-reference/index.mdx`, `grpc/index.mdx`, `transactions.mdx` |
+
+A description that is wrong upstream stays wrong until upstream fixes it. Record it, raise it, and do not paper over it locally. That is a real limit of a generated reference and it is better stated than hidden.
+
+## What to read
+
+Read the generated pages for a version, and sample rather than exhaustively grinding: the generator makes the same mistake on every page, so a defect is almost always a class. Three or four module pages of different shapes will surface nearly everything, and a pattern seen twice is a pattern.
+
+Prioritise the pages a reader actually lands on first: `bank`, `staking`, `gov`, `auth`, and whichever module changed most in this release.
+
+## What to look for
+
+**Grammar and spelling**, in the generator's own wording first. Upstream comment text is its own problem, but a typo the generator introduces is ours and appears everywhere.
+
+**House style**, from the root `CLAUDE.md`: no bold or italic in documentation content, no em-dashes, internal links as absolute Mintlify paths without `.mdx`. The generator should never emit any of these, so one occurrence is a template defect.
+
+**Whether it makes sense.** The question to hold is: could a competent reader who has not used this API before act on this page without guessing? Specifically:
+
+- Does a field description say what to put in the field, or only restate the field's name?
+- Does the page state the form of every value it asks for, or does it leave a placeholder a reader cannot fill? The runners already fail on this, so anything here is something they could not see.
+- Do the encoding notes agree with the transaction example directly below them?
+- Does a sentence assume knowledge the page never gives, or that lives only in `grpc/index.mdx`?
+- Is a heading or a note ambiguous between two methods with similar names?
+
+**Truncation and mangling.** Proto comments arrive with line breaks, code fences, and occasional markup. Look for a description cut mid-sentence, a stray backtick, a table cell that broke its row, a link that renders as literal text.
+
+## How to report
+
+Group findings by where they must be fixed, using the table above, because that is the order someone will act on them. For each: the page and anchor, the text as it stands, and what it should say.
+
+Say plainly when a class of problem is upstream and large. "Sixteen field descriptions across `staking` restate the field name and say nothing else" is a useful finding about upstream comment quality. Listing all sixteen is not.
+
+If nothing needs fixing, say so in a sentence. A prose review that manufactures findings to look thorough costs more attention than it saves.
+
+## Verifying a generator fix
+
+After changing `lib/render.js`, regenerate and confirm the fix landed everywhere the pattern appeared, not only on the page where you noticed it:
+
+```bash
+cd scripts/api-reference && GITHUB_TOKEN=$(gh auth token) npm run sync -- --version next
+npm test
+```
+
+The 77 unit tests assert generator behaviour by class, so add a case there for anything you fix. A wording defect that shipped once will ship again.

.github/workflows/check-tutorial-forward-port.yml

@@ -0,0 +1,63 @@
+name: Check example tutorials are forward-ported
+
+# The example chain tutorials are synced from cosmos/example into
+# sdk/next/tutorials/example/ by a bot in that repo. Nothing carries them into
+# sdk/latest/, so latest/ silently falls behind: it sat two syncs stale for
+# months, telling readers localnet runs several validators when it runs one
+# validator and three full nodes.
+#
+# These pages are the one exception to the version freeze. They instruct
+# `git clone https://github.com/cosmos/example` and `git checkout main`, so they
+# document whatever main is now rather than a released version. A frozen copy
+# protects nothing; it just describes code the reader is not running.
+#
+# So this fails a PR that changes next/ without the matching latest/ change, and
+# names the command that fixes it. It does not push the fix itself: the incoming
+# sync PR is opened by the other repo's workflow, and a bot editing a bot's PR is
+# harder to reason about than a red check with one command in it.
+
+on:
+  pull_request:
+    paths:
+      - "sdk/next/tutorials/example/**"
+      - "sdk/latest/tutorials/example/**"
+
+jobs:
+  forward-port:
+    name: latest/ matches next/
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Forward-port into a scratch copy and diff
+        run: |
+          set -o pipefail
+
+          # Run the real script, then ask git whether it changed anything. If it
+          # did, latest/ was behind and this PR would publish a stale tutorial.
+          node scripts/sync-next-to-latest.js sdk/next/tutorials/example/
+
+          if git diff --quiet -- sdk/latest/tutorials/example/; then
+            echo "latest/ already matches next/."
+            exit 0
+          fi
+
+          echo
+          echo "sdk/latest/tutorials/example/ is behind sdk/next/tutorials/example/."
+          echo
+          git --no-pager diff --stat -- sdk/latest/tutorials/example/
+          echo
+          echo "These pages tell the reader to check out cosmos/example main, so a"
+          echo "frozen latest/ copy documents code they are not running. Run:"
+          echo
+          echo "    node scripts/sync-next-to-latest.js sdk/next/tutorials/example/"
+          echo
+          echo "and commit the result to this PR."
+          exit 1