docs: publish SDK 0.22.0 (latest)

.vitepress/config.ts

@@ -215,6 +215,8 @@ export default defineConfig({
   lang: 'en',
   ignoreDeadLinks: true,
   lastUpdated: true,
+  // CLAUDE.md is an internal maintainer/agent runbook, not a public page.
+  srcExclude: ['CLAUDE.md', '**/CLAUDE.md'],
   vite: {
     plugins: [
       {
@@ -274,9 +276,9 @@ export default defineConfig({
       { text: 'Deployments', link: '/guide/deployments/' },
       { text: 'History', link: '/changelog' },
       {
-        text: 'v0.20.9 (latest)',
+        text: 'v0.22.0 (latest)',
         items: [
-          { text: 'v0.20.9 (latest)', link: '/' },
+          { text: 'v0.22.0 (latest)', link: '/' },
           { text: 'v0.16.23', link: '/0.16.23/' }
         ]
       }

CLAUDE.md

@@ -0,0 +1,68 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+VitePress documentation site for the AAStar SDK, served at https://docs.aastar.io. Content is authored as Markdown and **auto-generated from the `aastar-sdk` repo** — treat most pages under `api/`, `guide/`, and `examples/` as generated/synced output, not hand-maintained source. The only real "code" is `.vitepress/config.ts` (site config + sidebars) and `.vitepress/theme/`.
+
+## Commands
+
+```bash
+pnpm install              # install deps (use pnpm, not npm)
+./run.sh                  # dev server on port 5173 (kills any process already on that port)
+pnpm docs:dev             # raw dev server (vitepress)
+./build.sh                # clean .vitepress/cache then build → .vitepress/dist/
+pnpm docs:build           # raw build
+pnpm docs:preview         # preview the built site
+```
+
+There are no tests or linters in this repo.
+
+## Deployment
+
+Deployment is **git-push-driven**, despite some stale instructions in `README.md`/`LOCAL_DEV.md`:
+
+- `./deploy.sh ["commit message"]` stages all changes, commits, and pushes to `origin/main`, which triggers a **Cloudflare Pages** build.
+- `.vitepress/dist/` is gitignored and built by Cloudflare, not committed. Ignore README references to a Vercel flow, `package.json.backup`, or committing `dist/` — those are outdated. The license is **Apache-2.0** (footer/NOTICE), not the MIT in README.
+
+## Versioning model (the one non-obvious thing here)
+
+The site serves a "latest" version at the root and **frozen archived snapshots** under version-numbered directories (currently `0.16.23/`).
+
+- A frozen version is a **literal copy** of `guide/`, `api/`, `examples/`, `zh/`, `index.md`, and `changelog.md` placed under `<version>/` (e.g. `0.16.23/guide/...`). It has no own `.vitepress`.
+- In `.vitepress/config.ts`, the helper `prefixSidebar(items, '/<version>')` deep-clones the latest sidebars and rewrites every root-absolute `link` to be version-prefixed, so the archived snapshot reuses the latest sidebar structure without hand-editing. The `sidebar` map registers both root paths (`/guide/`, `/api/`, …) and prefixed paths (`/0.16.23/guide/`, …).
+- The `nav` version dropdown ("vX.Y.x (latest)" → older versions) is maintained by hand.
+
+**To freeze a new version**, the manual steps are: copy the current root content dirs into a new `<version>/` folder, then in `config.ts` add `<version>/...` entries to the `sidebar` map (via `prefixSidebar`) and add the version to the `nav` dropdown. `ARCHIVED_VERSION` is a single constant near the bottom of the config.
+
+## config.ts specifics
+
+- `ignoreDeadLinks: true` — dead links don't fail the build (expected, since content is synced from another repo).
+- A custom Vite middleware (`aastar-docs-rewrite-docs-prefix`) 302-redirects any `/docs` or `/docs/...` URL to the same path with the `/docs` prefix stripped. This runs in both dev and preview servers; keep both `configureServer` and `configurePreviewServer` copies in sync if you change it.
+- Search is local provider; site is bilingual (English at root, Chinese under `zh/`).
+
+## Secrets / CI
+
+The only GitHub Actions workflow is `.github/workflows/check-secrets.yml`, which scans the repo on push/PR for private keys and API tokens (Ethereum keys, PEM, AWS, OpenAI/Anthropic/Google AI keys, GitHub PATs, Stripe). It **fails the build** if any match. Never commit real keys or 64-hex-char `0x...` strings, even in example/doc Markdown — use placeholders. Real secrets go in `.env` (gitignored; see `.env.example`). Notes from hardening: the bare-`0x{64hex}` Ethereum heuristic is **skipped for Markdown** (blockchain docs are full of tx hashes / bytes32 / bytecode) but the contextual `private_key = "0x…"` check runs on every file; TypeDoc's `_media/` dir (example source with placeholder keys like `0x1234…`) is in `EXCLUDED_DIRS`.
+
+## Release runbook — track an SDK release → update docs → publish
+
+This is the repeatable procedure when **`aastar-sdk` cuts a new release** and the docs site must follow. Run it end-to-end; don't skip steps. (`$SDK` = `../aastar-sdk`, a sibling checkout.)
+
+1. **Determine the published version — from the right file.** In `$SDK`: `git fetch --tags && git checkout main && git pull`. The authoritative version is **`packages/sdk/package.json`** (+ `npm view @aastar/sdk version` + the `vX.Y.Z` git tag + top of `CHANGELOG.md`). ⚠️ **Never read the repo-root `package.json`** — in this monorepo root is `0.0.0-private` (and was misleadingly stale before that). Confirm the tag's commit; that's the release commit.
+2. **Regenerate the API docs at the release commit.** In `$SDK` on that commit: `pnpm run docs:generate` (TypeDoc → `$SDK/docs/api`). This makes the `Defined in` source links point at the release commit. (`docs/api` is git-tracked in the SDK; you don't have to commit it there — it just feeds the sync.)
+3. **Branch + sync.** In this repo: `git checkout main && git pull && git checkout -b docs/sync-sdk-<version>`, then run the SDK's `bash $SDK/scripts/extract-docs.sh`. That script is self-cleaning (path-resolved, dynamic package list from `typedoc.json` entryPoints, `rm -rf guide/docs`, `rsync --delete` examples) and runs `sanitize-typedoc-md.cjs` at the end. It preserves the docs-repo-owned `guide/{concepts,use-cases,deployments}` and the curated `examples/index.md`.
+4. **Reconcile the API sidebar.** Compare `ls api/@aastar` to the **latest** `apiSidebar` Core Modules in `config.ts`. If packages were added/removed, edit `apiSidebar` — but **leave `apiSidebarArchived` frozen** (it backs `/0.16.23/` and must keep that snapshot's old module set).
+5. **Bump the version labels** (the only routinely-hand-edited bit): the `nav` dropdown in `config.ts` (`vX.Y.Z (latest)`, two spots) and the `Status-…` badge in `index.md`.
+6. **Spot-check the things that drift:** no `MIT` residue in latest (`grep` excluding `0.16.23/` and the "如 MIT" example line — upstream is Apache now so this should be clean); `guide/docs/API_REFERENCE.md` shows the right `Version:` (upstream `update_versions.cjs` auto-bumps it); deployment addresses in `guide/deployments/*` still match `@aastar/core` `CANONICAL_ADDRESSES` (single source of truth, all 3 chains); every `/guide/docs/*` link in `config.ts` resolves (SDK occasionally renames pages).
+7. **Build, PR, verify CI.** `pnpm run docs:build` must pass locally (the sanitizer is what keeps it green). Commit (`api guide examples zh changelog.md .vitepress/config.ts index.md`), push, open a PR. Required-green checks: **Scan for Private Keys and Secrets** + **Cloudflare Pages**. Branch protection requires **1 approving review** and **`enforce_admins: true`** — so you cannot self-merge; the user (or a reviewer) must approve.
+8. **Publish = merge.** Merging to `main` auto-triggers the Cloudflare production build (there is no separate "publish" step). Confirm the main commit's `Cloudflare Pages` check goes `success`; then docs.aastar.io serves the new version.
+
+### Lessons banked (mistakes not to repeat)
+- **Monorepo version:** read `packages/sdk/package.json`, never repo-root. (Cost a wrong "it's only a tag-level bump" call.)
+- **TypeDoc ↔ VitePress:** prose pseudo-tags (`<jwt>`, `<void>`, `Promise<T>`) break the Vue compiler → the `sanitize-typedoc-md.cjs` pass is mandatory (now wired into the sync).
+- **Secret-scan false positives** on a docs repo come from bytecode / tx hashes / `_media` placeholder keys — fixed via Markdown-skip + `_media` exclusion; don't "fix" by deleting real content.
+- **Sidebar mirroring:** changing `apiSidebar` used to silently break the frozen `/0.16.23/` archive — that's why the archived sidebar is a separate frozen copy.
+- **Don't blanket-delete `guide/`** on sync: `concepts/`, `use-cases/`, `deployments/` are hand-maintained.
+- **Cross-repo coupling:** doc-source fixes (license badges, `API_REFERENCE.md` version) belong **upstream in the SDK** (tracked via SDK issues), else every sync reintroduces them.

api/@aastar/account/classes/UserOpClient.md

@@ -1,4 +1,4 @@
-Defined in: [packages/account/src/index.ts:40](https://github.com/AAStarCommunity/aastar-sdk/blob/f84ad01d4a6f445b93e18d397ea2859a5682be1a/packages/account/src/index.ts#L40)
+Defined in: [packages/account/src/index.ts:40](https://github.com/AAStarCommunity/aastar-sdk/blob/3f8cdd383a819db0bbb2a41052f39ff7981a46dc/packages/account/src/index.ts#L40)
 
 UserOperation Client for handling high-level flows
 
@@ -18,7 +18,7 @@ UserOperation Client for handling high-level flows
 
 > `static` **estimateGas**(`bundler`, `op`, `entryPoint`): `Promise`\<`any`\>
 
-Defined in: [packages/account/src/index.ts:41](https://github.com/AAStarCommunity/aastar-sdk/blob/f84ad01d4a6f445b93e18d397ea2859a5682be1a/packages/account/src/index.ts#L41)
+Defined in: [packages/account/src/index.ts:41](https://github.com/AAStarCommunity/aastar-sdk/blob/3f8cdd383a819db0bbb2a41052f39ff7981a46dc/packages/account/src/index.ts#L41)
 
 #### Parameters
 
@@ -38,7 +38,7 @@ Defined in: [packages/account/src/index.ts:41](https://github.com/AAStarCommunit
 
 > `static` **getReceipt**(`bundler`, `hash`): `Promise`\<`any`\>
 
-Defined in: [packages/account/src/index.ts:55](https://github.com/AAStarCommunity/aastar-sdk/blob/f84ad01d4a6f445b93e18d397ea2859a5682be1a/packages/account/src/index.ts#L55)
+Defined in: [packages/account/src/index.ts:55](https://github.com/AAStarCommunity/aastar-sdk/blob/3f8cdd383a819db0bbb2a41052f39ff7981a46dc/packages/account/src/index.ts#L55)
 
 #### Parameters
 
@@ -57,7 +57,7 @@ Defined in: [packages/account/src/index.ts:55](https://github.com/AAStarCommunit
 
 > `static` **sendUserOp**(`bundler`, `op`, `entryPoint`): `Promise`\<`any`\>
 
-Defined in: [packages/account/src/index.ts:48](https://github.com/AAStarCommunity/aastar-sdk/blob/f84ad01d4a6f445b93e18d397ea2859a5682be1a/packages/account/src/index.ts#L48)
+Defined in: [packages/account/src/index.ts:48](https://github.com/AAStarCommunity/aastar-sdk/blob/3f8cdd383a819db0bbb2a41052f39ff7981a46dc/packages/account/src/index.ts#L48)
 
 #### Parameters
 

api/@aastar/account/functions/createEOAWalletClient.md

@@ -1,6 +1,6 @@
 > **createEOAWalletClient**(`privateKey`, `chain`, `transport`): [`EOAWalletClient`](../type-aliases/EOAWalletClient.md)
 
-Defined in: [packages/account/src/eoa.ts:9](https://github.com/AAStarCommunity/aastar-sdk/blob/f84ad01d4a6f445b93e18d397ea2859a5682be1a/packages/account/src/eoa.ts#L9)
+Defined in: [packages/account/src/eoa.ts:9](https://github.com/AAStarCommunity/aastar-sdk/blob/3f8cdd383a819db0bbb2a41052f39ff7981a46dc/packages/account/src/eoa.ts#L9)
 
 ## Parameters
 

api/@aastar/account/functions/getUserOpHash.md

@@ -1,6 +1,6 @@
 > **getUserOpHash**(`op`, `ep`, `chainId`): `` `0x${string}` ``
 
-Defined in: [packages/account/src/index.ts:16](https://github.com/AAStarCommunity/aastar-sdk/blob/f84ad01d4a6f445b93e18d397ea2859a5682be1a/packages/account/src/index.ts#L16)
+Defined in: [packages/account/src/index.ts:16](https://github.com/AAStarCommunity/aastar-sdk/blob/3f8cdd383a819db0bbb2a41052f39ff7981a46dc/packages/account/src/index.ts#L16)
 
 Local implementation of EntryPoint v0.7 getUserOpHash
 

api/@aastar/account/functions/packUserOpLimits.md

@@ -1,6 +1,6 @@
 > **packUserOpLimits**(`high`, `low`): `` `0x${string}` ``
 
-Defined in: [packages/account/src/index.ts:9](https://github.com/AAStarCommunity/aastar-sdk/blob/f84ad01d4a6f445b93e18d397ea2859a5682be1a/packages/account/src/index.ts#L9)
+Defined in: [packages/account/src/index.ts:9](https://github.com/AAStarCommunity/aastar-sdk/blob/3f8cdd383a819db0bbb2a41052f39ff7981a46dc/packages/account/src/index.ts#L9)
 
 Common Pack Logic for v0.7 UserOperations
 

api/@aastar/account/functions/toSimpleSmartAccount.md

@@ -1,6 +1,6 @@
 > **toSimpleSmartAccount**(`parameters`): `Promise`\<[`SimpleSmartAccount`](../type-aliases/SimpleSmartAccount.md)\>
 
-Defined in: [packages/account/src/accounts/simple.ts:22](https://github.com/AAStarCommunity/aastar-sdk/blob/f84ad01d4a6f445b93e18d397ea2859a5682be1a/packages/account/src/accounts/simple.ts#L22)
+Defined in: [packages/account/src/accounts/simple.ts:22](https://github.com/AAStarCommunity/aastar-sdk/blob/3f8cdd383a819db0bbb2a41052f39ff7981a46dc/packages/account/src/accounts/simple.ts#L22)
 
 ## Parameters
 

api/@aastar/account/type-aliases/EOAWalletClient.md

@@ -1,6 +1,6 @@
 > **EOAWalletClient** = [`WalletClient`](https://viem.sh/docs/index.html) & `object`
 
-Defined in: [packages/account/src/eoa.ts:4](https://github.com/AAStarCommunity/aastar-sdk/blob/f84ad01d4a6f445b93e18d397ea2859a5682be1a/packages/account/src/eoa.ts#L4)
+Defined in: [packages/account/src/eoa.ts:4](https://github.com/AAStarCommunity/aastar-sdk/blob/3f8cdd383a819db0bbb2a41052f39ff7981a46dc/packages/account/src/eoa.ts#L4)
 
 ## Type Declaration
 

api/@aastar/account/type-aliases/SimpleSmartAccount.md

@@ -1,6 +1,6 @@
 > **SimpleSmartAccount** = [`LocalAccount`](https://viem.sh/docs/index.html) & `object`
 
-Defined in: [packages/account/src/accounts/simple.ts:15](https://github.com/AAStarCommunity/aastar-sdk/blob/f84ad01d4a6f445b93e18d397ea2859a5682be1a/packages/account/src/accounts/simple.ts#L15)
+Defined in: [packages/account/src/accounts/simple.ts:15](https://github.com/AAStarCommunity/aastar-sdk/blob/3f8cdd383a819db0bbb2a41052f39ff7981a46dc/packages/account/src/accounts/simple.ts#L15)
 
 ## Type Declaration
 

api/@aastar/admin/classes/ProtocolGovernance.md

@@ -1,4 +1,4 @@
-Defined in: [admin/src/ProtocolGovernance.ts:20](https://github.com/AAStarCommunity/aastar-sdk/blob/f84ad01d4a6f445b93e18d397ea2859a5682be1a/packages/admin/src/ProtocolGovernance.ts#L20)
+Defined in: [admin/src/ProtocolGovernance.ts:20](https://github.com/AAStarCommunity/aastar-sdk/blob/3f8cdd383a819db0bbb2a41052f39ff7981a46dc/packages/admin/src/ProtocolGovernance.ts#L20)
 
 ProtocolGovernance - L3 Pattern
 
@@ -17,7 +17,7 @@ Responsibilities:
 
 > **new ProtocolGovernance**(`config`): `ProtocolGovernance`
 
-Defined in: [admin/src/ProtocolGovernance.ts:24](https://github.com/AAStarCommunity/aastar-sdk/blob/f84ad01d4a6f445b93e18d397ea2859a5682be1a/packages/admin/src/ProtocolGovernance.ts#L24)
+Defined in: [admin/src/ProtocolGovernance.ts:24](https://github.com/AAStarCommunity/aastar-sdk/blob/3f8cdd383a819db0bbb2a41052f39ff7981a46dc/packages/admin/src/ProtocolGovernance.ts#L24)
 
 #### Parameters
 
@@ -51,7 +51,7 @@ Defined in: core/dist/clients/BaseClient.d.ts:5
 
 > **entryPointAddress**: `` `0x${string}` ``
 
-Defined in: [admin/src/ProtocolGovernance.ts:22](https://github.com/AAStarCommunity/aastar-sdk/blob/f84ad01d4a6f445b93e18d397ea2859a5682be1a/packages/admin/src/ProtocolGovernance.ts#L22)
+Defined in: [admin/src/ProtocolGovernance.ts:22](https://github.com/AAStarCommunity/aastar-sdk/blob/3f8cdd383a819db0bbb2a41052f39ff7981a46dc/packages/admin/src/ProtocolGovernance.ts#L22)
 
 #### Overrides
 
@@ -111,7 +111,7 @@ Defined in: core/dist/clients/BaseClient.d.ts:6
 
 > **registryAddress**: `` `0x${string}` ``
 
-Defined in: [admin/src/ProtocolGovernance.ts:21](https://github.com/AAStarCommunity/aastar-sdk/blob/f84ad01d4a6f445b93e18d397ea2859a5682be1a/packages/admin/src/ProtocolGovernance.ts#L21)
+Defined in: [admin/src/ProtocolGovernance.ts:21](https://github.com/AAStarCommunity/aastar-sdk/blob/3f8cdd383a819db0bbb2a41052f39ff7981a46dc/packages/admin/src/ProtocolGovernance.ts#L21)
 
 #### Overrides
 
@@ -123,7 +123,7 @@ Defined in: [admin/src/ProtocolGovernance.ts:21](https://github.com/AAStarCommun
 
 > **configureRole**(`params`, `options?`): `Promise`\<`` `0x${string}` ``\>
 
-Defined in: [admin/src/ProtocolGovernance.ts:95](https://github.com/AAStarCommunity/aastar-sdk/blob/f84ad01d4a6f445b93e18d397ea2859a5682be1a/packages/admin/src/ProtocolGovernance.ts#L95)
+Defined in: [admin/src/ProtocolGovernance.ts:95](https://github.com/AAStarCommunity/aastar-sdk/blob/3f8cdd383a819db0bbb2a41052f39ff7981a46dc/packages/admin/src/ProtocolGovernance.ts#L95)
 
 Configure a Role's parameters (Admin only).
 Reads the current on-chain config first, then merges the provided overrides
@@ -169,7 +169,7 @@ Get the account address of the connected wallet
 
 > **getProtocolParams**(): `Promise`\<[`ProtocolParams`](../interfaces/ProtocolParams.md)\>
 
-Defined in: [admin/src/ProtocolGovernance.ts:137](https://github.com/AAStarCommunity/aastar-sdk/blob/f84ad01d4a6f445b93e18d397ea2859a5682be1a/packages/admin/src/ProtocolGovernance.ts#L137)
+Defined in: [admin/src/ProtocolGovernance.ts:137](https://github.com/AAStarCommunity/aastar-sdk/blob/3f8cdd383a819db0bbb2a41052f39ff7981a46dc/packages/admin/src/ProtocolGovernance.ts#L137)
 
 #### Returns
 
@@ -279,7 +279,7 @@ Defined in: core/dist/clients/BaseClient.d.ts:21
 
 > **setStaking**(`staking`, `options?`): `Promise`\<`` `0x${string}` ``\>
 
-Defined in: [admin/src/ProtocolGovernance.ts:82](https://github.com/AAStarCommunity/aastar-sdk/blob/f84ad01d4a6f445b93e18d397ea2859a5682be1a/packages/admin/src/ProtocolGovernance.ts#L82)
+Defined in: [admin/src/ProtocolGovernance.ts:82](https://github.com/AAStarCommunity/aastar-sdk/blob/3f8cdd383a819db0bbb2a41052f39ff7981a46dc/packages/admin/src/ProtocolGovernance.ts#L82)
 
 Set the Staking contract address
 
@@ -300,7 +300,7 @@ Set the Staking contract address
 
 > **setSuperPaymaster**(`paymaster`, `options?`): `Promise`\<`` `0x${string}` ``\>
 
-Defined in: [admin/src/ProtocolGovernance.ts:71](https://github.com/AAStarCommunity/aastar-sdk/blob/f84ad01d4a6f445b93e18d397ea2859a5682be1a/packages/admin/src/ProtocolGovernance.ts#L71)
+Defined in: [admin/src/ProtocolGovernance.ts:71](https://github.com/AAStarCommunity/aastar-sdk/blob/3f8cdd383a819db0bbb2a41052f39ff7981a46dc/packages/admin/src/ProtocolGovernance.ts#L71)
 
 Approve a new SuperPaymaster contract address
 
@@ -321,7 +321,7 @@ Approve a new SuperPaymaster contract address
 
 > **setTreasury**(`treasury`, `options?`): `Promise`\<`` `0x${string}` ``\>
 
-Defined in: [admin/src/ProtocolGovernance.ts:40](https://github.com/AAStarCommunity/aastar-sdk/blob/f84ad01d4a6f445b93e18d397ea2859a5682be1a/packages/admin/src/ProtocolGovernance.ts#L40)
+Defined in: [admin/src/ProtocolGovernance.ts:40](https://github.com/AAStarCommunity/aastar-sdk/blob/3f8cdd383a819db0bbb2a41052f39ff7981a46dc/packages/admin/src/ProtocolGovernance.ts#L40)
 
 Update the Global Treasury Address where protocol fees are collected
 
@@ -342,7 +342,7 @@ Update the Global Treasury Address where protocol fees are collected
 
 > **transferToDAO**(`daoAddress`, `options?`): `Promise`\<`` `0x${string}` ``\>
 
-Defined in: [admin/src/ProtocolGovernance.ts:125](https://github.com/AAStarCommunity/aastar-sdk/blob/f84ad01d4a6f445b93e18d397ea2859a5682be1a/packages/admin/src/ProtocolGovernance.ts#L125)
+Defined in: [admin/src/ProtocolGovernance.ts:125](https://github.com/AAStarCommunity/aastar-sdk/blob/3f8cdd383a819db0bbb2a41052f39ff7981a46dc/packages/admin/src/ProtocolGovernance.ts#L125)
 
 Transfer Protocol Ownership to a DAO (Multisig/Timelock)
 This is the final step of "Protocol Admin" lifecycle.
@@ -364,7 +364,7 @@ This is the final step of "Protocol Admin" lifecycle.
 
 > **updateEntryPoint**(`entryPoint`, `options?`): `Promise`\<`` `0x${string}` ``\>
 
-Defined in: [admin/src/ProtocolGovernance.ts:57](https://github.com/AAStarCommunity/aastar-sdk/blob/f84ad01d4a6f445b93e18d397ea2859a5682be1a/packages/admin/src/ProtocolGovernance.ts#L57)
+Defined in: [admin/src/ProtocolGovernance.ts:57](https://github.com/AAStarCommunity/aastar-sdk/blob/3f8cdd383a819db0bbb2a41052f39ff7981a46dc/packages/admin/src/ProtocolGovernance.ts#L57)
 
 Update the supported EntryPoint address