Skip to content

docs: refresh getting-started onboarding cluster for current agoric-sdk - #1303

Closed
igoricbot wants to merge 1 commit into
Agoric:mainfrom
igoricbot:docs/getting-started-refresh-20260924
Closed

igoricbot wants to merge 1 commit into
Agoric:mainfrom
igoricbot:docs/getting-started-refresh-20260924

Conversation

@igoricbot

Copy link
Copy Markdown

Summary

Refreshes the getting-started onboarding cluster against current agoric-sdk:

  • Bump the required Node.js version from the EOL v18.18.0 to v22.11.0, matching agoric-sdk's engines.node (^22.11 || ^24.14).
  • Update the Yarn install step: the guide described Yarn 1 with yarn set version 1.22.5, but the default dapp-offer-up template pins Yarn Berry ("packageManager": "yarn@4.7.0"). Corrected accordingly.
  • Fix a bigint literal bug in the sell-concert-tickets code sample (backRow used a bare n where AmountMath.make/maxTickets need bigint literals).
  • Retire deploying.md, which described the retired ag-solo agoric deploy model (home object, contract/deploy.js + api/deploy.js, the REPL, agoric init defaulting to dapp-fungible-faucet) that matches no current template. The current core-eval flow is already documented accurately in explainer-deploying-a-smart-contact.md; added a redirect from the old path and fixed the one inbound link (plus a stale zoe.install(bundle) sample, now zoe.installBundleID(bundleId)) in guides/js-programming/eventual-send.md.
  • Fix a "Deploying a Smart Contact" title typo (-> "Contract").
  • Soften a swaparoo doc's dated "due to a bug, which will be addressed in an upcoming release" note — the bug is still present upstream, so the promise is misleading.
  • Bump one ui-tutorial dependency pin (@interchain-ui/react 1.22.11 -> 1.23.11) to match what agoric-labs/ui-tutorial's checkpoint branches actually pin.

Verification notes

Checked against live agoric-sdk (engines, CLI defaults in packages/agoric-cli/src/main.js), the Agoric/dapp-offer-up and Agoric/dapp-agoric-basics template repos, and agoric-labs/ui-tutorial's checkpoint-1 through checkpoint-5 branches.

Notably, the seven ui-tutorial/ pages' code samples and dependency pins (@agoric/react-components, @agoric/web-components, @agoric/rpc, @agoric/store, cosmos-kit) turn out to match the actual checkpoint branches exactly, word for word in the React source. They lag the unreleased tip of Agoric/ui-kit, whose API has since diverged in breaking ways (AgoricProvider props, which package exports useAgoric), but agoric-labs/ui-tutorial itself has not been updated to that tip. Bumping the docs' pins to ui-kit's latest would break the tutorial rather than fix it, so those pins were left as-is (aside from the one confirmed drift above).

contract-rpc.md's source permalinks pinned to the mainnet1B tag were also re-checked line-by-line against that tag and found accurate.

Test plan

  • yarn docs:build (includes the internal link checker) passes locally
  • Spot-checked external links referenced from the touched pages (community forum, Discord, GitHub, Keplr) resolve
  • Not independently re-verified: non-code-sample prose in pages marked "up-to-date"/unchanged by the survey and left untouched here

🤖 Generated with Claude Code

Node.js requirement was pinned to the EOL v18.18.0; bump to v22.11.0 to
match agoric-sdk's engines range (^22.11 || ^24.14). The Yarn install
step still described Yarn 1 with a corepack pin of 1.22.5, but the
default dapp-offer-up template pins Yarn Berry 4.7.0; update the guide
to match. Fix a bigint literal bug in the sell-concert-tickets code
sample (bare `n` where `1n`/`10n` bigints are required). Retire
deploying.md, which described the retired ag-solo `agoric deploy`
model (home object, contract/deploy.js + api/deploy.js, REPL) that no
longer matches any current dapp template; the current core-eval flow
is already documented accurately in
explainer-deploying-a-smart-contact.md, so redirect the old path there
and fix its one inbound link plus a stale zoe.install() code sample in
eventual-send.md. Fix "Smart Contact" title typo. Soften a swaparoo
doc's dated "will be addressed in an upcoming release" promise about a
namesByAddressAdmin bug that is still unfixed upstream. Bump one
ui-tutorial dependency pin (@interchain-ui/react 1.22.11 -> 1.23.11)
to match what agoric-labs/ui-tutorial's checkpoint branches actually
pin.

Verified against live agoric-sdk (engines, CLI defaults), the
dapp-offer-up and dapp-agoric-basics template repos, and the
agoric-labs/ui-tutorial checkpoint-1..5 branches: the seven ui-tutorial
pages' code samples and dependency pins (@agoric/react-components,
@agoric/web-components, @agoric/rpc, @agoric/store, cosmos-kit) match
the actual checkpoint branches exactly, despite lagging the unreleased
tip of Agoric/ui-kit, whose API has since diverged in breaking ways
(AgoricProvider props, useAgoric's package). Bumping those pins to
ui-kit's latest would break the tutorial rather than fix it, since
agoric-labs/ui-tutorial has not itself been updated; left as-is.
contract-rpc.md's mainnet1B source permalinks were also re-verified
line-by-line against that tag and found accurate, contrary to the
survey's suspicion of drift.

yarn docs:build (including the internal link checker) passes locally.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@igoricbot igoricbot closed this Sep 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant