fix: improve tutorial setup and devnet script synchronization

[yfeng2824]

Summary

• Improve setup and usage across the token, CKB transfer, DOB, store-data, and Simple Lock tutorials.

Changes

• Replace shell-specific network commands with Windows-compatible npm and pnpm scripts, and default the token, transfer, and DOB examples to Devnet.
• Refresh local OffCKB system-script dependencies before starting the token, transfer, and DOB examples, and use the refreshed configuration for the DOB example’s Spore SDK.
• Refresh and validate the selected network’s Simple Lock system-script dependencies during deployment while preserving other networks.
• Prevent empty preimages from generating a Simple Lock funding address and add input guidance.
• Extend the shared setup component with project-specific paths and instructions.
• Clarify xUDT token identifiers, flags, complete token args, prefilled Devnet keys, and issue/query/transfer steps.
• Update account instructions to show how to reveal Devnet private keys and clarify Testnet setup.
• Add regression coverage for script synchronization, DOB configuration, and empty preimages.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
nervos-ckb-docs	Ready	Preview	Sep 29, 2026 2:35am UTC

[humble-little-bear]

CKB Docs Writing Review

Summary

This is a solid editorial improvement overall: the Windows-compatible npm run start:testnet instructions are consistent with the new package scripts, the new OffCKB account wording in _StartDevnet.mdx is clearer and safer (hiding private keys by default, with a valid link to OffCKB's #accounts docs), and the bolded UI labels in create-token.mdx (Issue Custom Token, Token xUDT args, View Custom Token, Query Issued Token) all match the actual labels in the example app. The main concerns are one misleading phrase in create-token.mdx ("public development key" for what is a private key field) and a few consistency nits in dash style, bolding, and capitalization.

Findings

• website/docs/dapp/create-token.mdx:L68: clarity: "prefilled with the first pre-funded OffCKB Devnet account's public development key" is misleading — the form field is labeled "Private Key" and requires the account's *private* key (validated against a 64-hex-char regex; the prefilled value is 0x6109…). "Public development key" reads as "public key", and pasting the actual public key will fail validation. Suggest "prefilled with the first pre-funded OffCKB Devnet account's private key (a publicly known development key — never use it for Mainnet or real assets)". [confidence: high]
• website/docs/dapp/create-token.mdx:L29: consistency: the TutorialHeader time "10–15 min after setup" uses an en dash, while the sibling tutorials use a spaced hyphen: create-dob "5 - 10 min", transfer-ckb "2 - 5 min", write-message "2 - 5 min", simple-lock "30 - 45 min first setup; 10 - 15 min afterward". Suggest "10 - 15 min after setup". [confidence: medium]
• website/docs/dapp/create-token.mdx:L40-L41: consistency: in the three-item list, only item 3 bolds its lead-in ("**Establish a Unique Token ID:**") while items 1 and 2 ("Create a Special Cell:", "Configure the Cell's Data:") are unbolded. Bold all three lead-ins or none. [confidence: medium]
• website/docs/dapp/create-token.mdx:L40: clarity: "the Script's args field contains the issuer's 32-byte Lock Script hash followed by the four-byte flags field" — the sentence mentions both a Type Script (xUDT) and a Lock Script, so bare "the Script's args field" is ambiguous. Suggest "the xUDT Script's args field". [confidence: medium]
• website/docs/dapp/create-token.mdx:L71: clarity: "not the Lock Script args shown in the account information" — the app has no UI element called "account information"; the Issue form shows a list with Balance, Lock Script (JSON), and Lock Script Hash. Suggest naming the actual element, e.g. "not the args field inside the **Lock Script** JSON shown above the form". [confidence: medium]
• website/docs/dapp/create-token.mdx:L122: consistency: "add the xUDT script dependency" uses lowercase "script", while this page capitalizes "xUDT Script" everywhere else (L40, L109, and the overview). Suggest "add the xUDT Script dependency". [confidence: medium]
• examples/dApp/xudt/README.md:L5-L7: consistency: the xudt, create-dob, and simple-transfer examples now ship the same sync:devnet/start:testnetscripts and identical startup behavior, but the xudt README describes it with different wording ("exports the local OffCKB Devnet scripts and updates only thedevnetsection" vs "refreshes the Devnet section ofsystem-scripts.json … Startup stops if the export fails or required scripts are missing"). Consider using the same two paragraphs in all three READMEs so readers see one explanation of one behavior. [confidence: low]
• examples/dApp/xudt/README.md:L5: clarity: "If the export fails or is missing the secp256k1 signing script or xUDT script" — the second clause dangles (the export "is missing" the script). Suggest "If the export fails or the result is missing the secp256k1 signing script or the xUDT script". [confidence: low]
• website/docs/dapp/create-dob.mdx:L80: consistency (pre-existing): heading "## Behind the Scene" vs "## Behind the Scenes" in create-token.mdx (L76); transfer-ckb.mdx also uses the singular. This PR already touches all three pages — worth aligning while here. [confidence: low]

Terminology cross-checks

• xUDT Script: the PR consistently uses title-case "xUDT Script" except once ("xUDT script dependency", L122). Recommendation: capitalize per the Script-type proper-noun convention.
• Lock Script hash: the PR normalizes the page's earlier "Lock Script Hash" to "Lock Script hash", which is now internally consistent within create-token.mdx. No change needed.
• Devnet / Testnet / Mainnet: capitalized consistently across the changed pages and example READMEs; matches existing docs usage. The _SwitchToTestnet component's npm run start:testnet text is accurate for its remaining consumers (create-dob.mdx, transfer-ckb.mdx) — both examples gained that script in this PR.
• Prefilled key label: the tutorial's new wording ("public development key") vs the app's actual field label ("Private Key"). Recommendation: keep doc wording aligned with the UI label so readers can find the field; see the L68 finding.
• Verified: the new link https://github.com/ckb-devrel/offckb#accounts resolves (the offckb README has an ## Accounts heading) and the documented offckb accounts --show-private-keys flag exists there; the "32-byte Lock Script hash + four-byte flags field 00000000" description is technically accurate; the console.log("The transaction hash is", txHash) fix corrects a real variable-name bug in the docs.

Questions

• In create-token.mdx L68, was "public development key" intended to mean "publicly known development private key"? If so, rephrasing along the lines suggested above would remove the public-key/private-key ambiguity.
• website/docs/dapp/write-message.mdx gets the new projectPath prop but keeps its own setup text; just confirming the store-data-on-cell example intentionally has no start:testnet mention in the tutorial, since it also lacks a SwitchToTestnet section — no action needed if deliberate.

[humble-little-bear]

Factual accuracy review — automated (ckb-docs-fact-checker)

Reviewed all added/modified lines in website/docs/** and examples/** (.md/.mdx) against authoritative sources (nervosnetwork/ckb develop, nervosnetwork/rfcs master, plus the example code in this PR and the ckb-devrel/offckb source for OffCKB CLI behavior).

Key claims verified:

• xUDT args = 32-byte owner Lock Script hash + 4-byte flags field (create-token.mdx) — matches RFC 0052 (rfcs/0052-extensible-udt/0052-extensible-udt.md): args: <owner lock script hash> <xUDT args> with <4-byte xUDT flags> <extension data>.
• All-zero flags mean no extension Scripts and the input-lock owner-mode check stays enabled — matches RFC 0052: "If flags & 0x1FFFFFFF is 0, no extension data is required" and owner mode via input lock script applies "when flags & 0x20000000 is zero or flags is not present".
• offckb accounts hides private keys by default; --show-private-keys reveals them (_StartDevnet.mdx) — matches offckb src/cli.ts (--show-private-keys, "hidden by default") and src/cmd/accounts.ts.
• Prefilled Issue Custom Token key is the first pre-funded OffCKB Devnet account key (create-token.mdx) — matches xudt/index.tsx default and offckb src/cfg/account.ts first entry.
• npm run start:testnet / pnpm dev:testnet commands — exist in the corresponding package.json files changed in this PR; _SwitchToTestnet is only used by tutorials whose examples gained start:testnet.
• Devnet default when NETWORK is unset; Testnet startup skips the sync refresh — matches the ccc-client.ts and package.json changes.
• "File ... generated successfully." export output and UI labels ("Token xUDT args", "View Custom Token", "Query Issued Token") — match offckb's export success message and the xudt example UI.

LGTM, No factual-review issues found.