docs(sdk): fix and expand the Upgrades and Cosmovisor guides

[evanorti]

Corrects broken code in the upgrade guide, restructures it for first-time readers, and modernizes the Cosmovisor example. All verified against Cosmos SDK v0.54 by running a real upgrade, store migration, and Cosmovisor run end to end.

upgrade.mdx:

Fixed the InitGenesis override snippet (used context.Context where sdk.Context is required), InitChainer now handles the SetModuleVersionMap error, and added the correct x/upgrade import path for v0.54.
Reordered around a lifecycle overview, added x/upgrade setup and a real migration body, and a counter upgrade example linking the tutorial and cosmos/example.

cosmovisor.mdx:

Fixed BeginBlocker→PreBlocker, simapp/upgrade.go→upgrades.go, and added the prepare-upgrade command.
Rewrote the SimApp example from v0.47→v0.50 to a tested v0.53.7→v0.54.3 run; bumped pins to v1.7.1.

[greptile-apps]

Greptile Summary

This PR fixes and expands the Cosmovisor and upgrade guides for Cosmos SDK v0.54, correcting broken code snippets and rewriting the SimApp walkthrough around a tested v0.53.7→v0.54.3 end-to-end run. Changes are applied identically to both sdk/latest/ and sdk/next/.

• cosmovisor.mdx: Fixes BeginBlocker→PreBlocker, bumps the Cosmovisor pin from v1.5.0 to v1.7.1, adds the prepare-upgrade command, updates all simd CLI invocations to the v0.54 subcommand style (config set client, comet unsafe-reset-all), and replaces the old v0.47→v0.50 walkthrough with a fully verified v0.53.7→v0.54.3 run including expected log output and verification commands.
• upgrade.mdx: Adds a lifecycle overview section and an x/upgrade wiring guide with a concrete Migrator/Migrate1to2 example; fixes the InitGenesis override to use sdk.UnwrapSDKContext (the handler provides context.Context, not sdk.Context); properly handles the error returned by SetModuleVersionMap in InitChainer; and adds a complete counter module upgrade worked example.

Confidence Score: 4/5

Safe to merge after fixing the two bold-text style violations in the cosmovisor intro paragraph.

The documentation changes are well-reasoned and the author verified them end-to-end against real SDK versions. The only finding is cosmetic: two version strings are wrapped in bold in both cosmovisor files, which the repo style rules explicitly prohibit. All code snippets, CLI commands, and import paths look accurate for v0.54.

sdk/latest/guides/upgrades/cosmovisor.mdx and sdk/next/guides/upgrades/cosmovisor.mdx — both have the bold version strings on the SimApp example intro line.

Important Files Changed

Filename	Overview
sdk/latest/guides/upgrades/cosmovisor.mdx	Modernizes SimApp example from v0.47→v0.50 to a tested v0.53.7→v0.54.3 run; fixes BeginBlocker→PreBlocker, bumps Cosmovisor pin to v1.7.1, adds prepare-upgrade command. One style issue: bold text for version strings violates repo style rules.
sdk/latest/guides/upgrades/upgrade.mdx	Adds upgrade lifecycle overview, x/upgrade wiring section, a concrete Migrate1to2 counter example, and a worked end-to-end counter module upgrade. Fixes sdk.Context vs context.Context in InitGenesis override and properly handles the SetModuleVersionMap error. No issues found.
sdk/next/guides/upgrades/cosmovisor.mdx	Mirror of sdk/latest changes (same content, adjusted internal link paths). Same bold text style violation on the version string line.
sdk/next/guides/upgrades/upgrade.mdx	Mirror of sdk/latest changes (same content, adjusted internal link paths). All code fixes and new sections are correctly applied. No issues found.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Gov as Governance
    participant Chain as Chain (v0.53.7)
    participant CV as Cosmovisor
    participant New as Chain (v0.54.3)

    Gov->>Chain: "MsgSoftwareUpgrade (height=85, name=v053-to-v054)"
    Chain-->>Chain: x/upgrade records plan
    Note over Chain: Block height reaches 85
    Chain->>CV: UPGRADE needed, write upgrade-info.json
    Chain-->>Chain: Halt
    CV->>CV: Switch symlink to upgrades/v053-to-v054/bin/simd
    CV->>New: Start new binary
    New->>New: PreBlock: x/upgrade runs handler, RunMigrations
    New-->>New: Modules migrated, VersionMap updated
    New->>New: Chain continues on v0.54.3

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Gov as Governance
    participant Chain as Chain (v0.53.7)
    participant CV as Cosmovisor
    participant New as Chain (v0.54.3)

    Gov->>Chain: "MsgSoftwareUpgrade (height=85, name=v053-to-v054)"
    Chain-->>Chain: x/upgrade records plan
    Note over Chain: Block height reaches 85
    Chain->>CV: UPGRADE needed, write upgrade-info.json
    Chain-->>Chain: Halt
    CV->>CV: Switch symlink to upgrades/v053-to-v054/bin/simd
    CV->>New: Start new binary
    New->>New: PreBlock: x/upgrade runs handler, RunMigrations
    New-->>New: Modules migrated, VersionMap updated
    New->>New: Chain continues on v0.54.3

Loading

_{Reviews (1): Last reviewed commit: "update update guides" | Re-trigger Greptile}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
cosmos-docs	🟢 Ready	View Preview	Jul 17, 2026, 8:57 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.