docs: API reference and getting-started guide for developers.pezkuwichain.io (#21)

* docs: generate the API reference for developers.pezkuwichain.io

Add TypeDoc (0.28.20) and `yarn docs`, which builds the reference for the
nine public API packages from src/ into build-docs/, with a landing page
and a getting-started guide whose examples were run against the live
network. The PR workflow builds it so a broken doc comment or config is
caught before merge.

docs/ held only a redirect to polkadot.js.org; it now holds the guide
sources. The README, packages/api/README.md and three CHANGELOG entries
linked to js.pezkuwichain.app, a domain that is not ours and is listed
for sale; they now point to developers.pezkuwichain.io, the Pezkuwi
Portal, or the upstream polkadot.js.org pages the entries came from.

* ci(docs): deploy the reference to developers.pezkuwichain.io

On every master push that changes the generated reference, build it with
`yarn docs` and publish it to the web host the same way pezkuwi-apps
publishes the portal: an approved production environment holds the deploy
key, the bundle is unpacked into releases/<sha>, and going live is one
rename of the current symlink. The switch is checked through nginx for the
public name (deploy sha, index, main.js, search index) and rolled back if
the new release is not served. workflow_dispatch with rollback_to makes an
earlier release live again.

Release-bot version bumps ([CI Skip]) and changes that cannot affect the
output do not ask for an approval.

.github/deploy/release.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# Runs on the web host as the docs-deploy user, fed over ssh by docs-deploy.yml.
+#
+#   release.sh deploy <sha>     unpack incoming/<sha>.tgz and make it live
+#   release.sh rollback <sha>   make an already unpacked release live again
+#
+# nginx serves /var/www/subdomains/developers, a symlink to $BASE/current, which
+# in turn points at releases/<sha>. Going live is one rename of that link, so a
+# reader never sees a half-copied tree, and the previous release stays on disk
+# for an instant rollback. Same layout as the apps deploy in pezkuwi-apps.
+set -euo pipefail
+
+BASE=${DOCS_DEPLOY_BASE:-/var/www/docs-deploy}
+SITE=developers.pezkuwichain.io
+KEEP=5
+
+mode=${1:?mode}
+sha=${2:?sha}
+[[ $sha =~ ^[0-9a-f]{40}$ ]] || { echo "not a commit sha: $sha"; exit 1; }
+
+rel=$BASE/releases/$sha
+
+switch_to () {
+  ln -sfn "releases/$1" "$BASE/current.new"
+  mv -T "$BASE/current.new" "$BASE/current"
+}
+
+# The answer has to come through nginx for the public name, not from the
+# disk: that is the path a visitor takes.
+served_sha () {
+  curl -sf --max-time 10 --resolve "$SITE:443:127.0.0.1" "https://$SITE/.deploy-sha"
+}
+
+check_live () {
+  local want=$1
+  [ "$(served_sha)" = "$want" ] || return 1
+  # The page must render: the index has to name TypeDoc's script, and the
+  # script and the search index have to be served too.
+  curl -sf --max-time 10 --resolve "$SITE:443:127.0.0.1" "https://$SITE/" \
+    | grep -q 'src="assets/main.js"' || return 1
+  curl -sf --max-time 10 -o /dev/null --resolve "$SITE:443:127.0.0.1" "https://$SITE/assets/main.js" || return 1
+  curl -sf --max-time 10 -o /dev/null --resolve "$SITE:443:127.0.0.1" "https://$SITE/assets/search.js"
+}
+
+prev=$(readlink "$BASE/current" || true)
+
+case $mode in
+  deploy)
+    tgz=$BASE/incoming/$sha.tgz
+    rm -rf "$rel.tmp"
+    mkdir -p "$rel.tmp"
+    tar -xzf "$tgz" -C "$rel.tmp"
+    [ -f "$rel.tmp/index.html" ] || { echo "no index.html in the bundle"; exit 1; }
+    [ "$(cat "$rel.tmp/.deploy-sha")" = "$sha" ] || { echo ".deploy-sha does not match $sha"; exit 1; }
+    rm -rf "$rel"
+    mv "$rel.tmp" "$rel"
+    rm -f "$tgz"
+    ;;
+  rollback)
+    [ -d "$rel" ] || { echo "no unpacked release $sha"; ls "$BASE/releases"; exit 1; }
+    ;;
+  *)
+    echo "unknown mode: $mode"; exit 1 ;;
+esac
+
+switch_to "$sha"
+
+if ! check_live "$sha"; then
+  echo "$SITE does not serve $sha after the switch"
+  if [ -n "$prev" ]; then
+    switch_to "${prev#releases/}"
+    echo "restored ${prev#releases/}"
+  fi
+  exit 1
+fi
+echo "live: $sha (was ${prev#releases/})"
+
+# Keep the newest releases, and always the one just replaced.
+cd "$BASE/releases"
+ls -1t | tail -n +$((KEEP + 1)) | while read -r old; do
+  [ "$old" = "$sha" ] || [ "releases/$old" = "$prev" ] || rm -rf -- "$old"
+done

.github/workflows/docs-deploy.yml

@@ -0,0 +1,92 @@
+name: Docs
+on:
+  push:
+    branches:
+      - master
+    # Only what changes the generated reference. Every run asks for an approval,
+    # and an approval request that cannot matter teaches people to tap without
+    # reading.
+    paths:
+      - 'packages/**'
+      - 'docs/**'
+      - 'typedoc.config.mjs'
+      - 'yarn.lock'
+      - '.github/deploy/**'
+      - '.github/workflows/docs-deploy.yml'
+  workflow_dispatch:
+    inputs:
+      rollback_to:
+        description: 'Make an earlier release live again (full commit sha); empty = deploy this commit'
+        required: false
+        default: ''
+
+# Deploys wait for each other; a newer push queues behind a running one.
+concurrency:
+  group: deploy-docs
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    # The release bot's version-bump commits change no source.
+    if: github.event.inputs.rollback_to == '' && !startsWith(github.event.head_commit.message, '[CI Skip]')
+    runs-on: ubuntu-latest
+    env:
+      YARN_ENABLE_SCRIPTS: false
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-node@v4
+      with:
+        node-version: 'lts/*'
+    - name: docs
+      run: |
+        yarn install --immutable
+        yarn docs
+        echo "$GITHUB_SHA" > build-docs/.deploy-sha
+        tar -C build-docs -czf docs-www.tgz .
+    - uses: actions/upload-artifact@v4
+      with:
+        name: docs-www
+        path: docs-www.tgz
+        retention-days: 7
+
+  # The only job that names the environment, so a run asks for approval once,
+  # and the deploy secrets (environment-scoped) exist only after it is given.
+  deploy:
+    needs: build
+    if: always() && (needs.build.result == 'success' || (needs.build.result == 'skipped' && github.event.inputs.rollback_to != ''))
+    runs-on: ubuntu-latest
+    environment: production
+    env:
+      HOST: ${{ secrets.DOCS_DEPLOY_HOST }}
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        sparse-checkout: .github/deploy
+    - name: ssh setup
+      env:
+        KEY: ${{ secrets.DOCS_DEPLOY_SSH_KEY }}
+        KNOWN_HOSTS: ${{ secrets.DOCS_DEPLOY_KNOWN_HOSTS }}
+      run: |
+        install -m 700 -d ~/.ssh
+        printf '%s\n' "$KEY" > ~/.ssh/id_ed25519
+        chmod 600 ~/.ssh/id_ed25519
+        printf '%s\n' "$KNOWN_HOSTS" > ~/.ssh/known_hosts
+    - uses: actions/download-artifact@v4
+      if: github.event.inputs.rollback_to == ''
+      with:
+        name: docs-www
+    - name: upload
+      if: github.event.inputs.rollback_to == ''
+      run: scp -o BatchMode=yes docs-www.tgz "docs-deploy@$HOST:/var/www/docs-deploy/incoming/$GITHUB_SHA.tgz"
+    - name: go live
+      env:
+        ROLLBACK_TO: ${{ github.event.inputs.rollback_to }}
+      run: |
+        if [ -n "$ROLLBACK_TO" ]; then set -- rollback "$ROLLBACK_TO"; else set -- deploy "$GITHUB_SHA"; fi
+        # ssh hands its arguments to the remote shell as one string: only a
+        # bare sha may get there.
+        [[ $2 =~ ^[0-9a-f]{40}$ ]] || { echo "not a full commit sha: $2"; exit 1; }
+        ssh -o BatchMode=yes "docs-deploy@$HOST" bash -s -- "$@" < .github/deploy/release.sh

.github/workflows/pr-any.yml

@@ -11,7 +11,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        step: ['lint', 'test', 'build']
+        step: ['lint', 'test', 'build', 'docs']
     runs-on: ubuntu-latest
     env:
       YARN_ENABLE_SCRIPTS: false

CHANGELOG.md

@@ -1984,7 +1984,7 @@ Changes:
 
 Upgrade priority: Low. Recommended for TS users with their own non-Pezkuwi/Zagros chains.
 
-- **Breaking changes** For TS users the default API augmentation is now optional. This means that the API, for TypeScript, is not decorated by default with the Bizinikiwi types and encpoints. TS users should add a singular `import '@pezkuwi/api-augment';` in their code to restore old behavior. A full writeup of the rationale and other options can be found [in the FAQ](https://js.pezkuwichain.app/docs/api/FAQ#since-upgrading-to-the-7x-series-typescript-augmentation-is-missing)
+- **Breaking changes** For TS users the default API augmentation is now optional. This means that the API, for TypeScript, is not decorated by default with the Bizinikiwi types and encpoints. TS users should add a singular `import '@pezkuwi/api-augment';` in their code to restore old behavior. A full writeup of the rationale and other options can be found [in the FAQ](https://polkadot.js.org/docs/api/FAQ#since-upgrading-to-the-7x-series-typescript-augmentation-is-missing)
 
 - **Breaking change** To cater for the above, chain-specific interfaces generated with older versions may not be compatible with the current version of the API. Additionally, TS interfaces generated with this version of the API is not compatible with older API versions.
 
@@ -3333,7 +3333,7 @@ Changes:
 
 Upgrade priority: Low. Recommended for `api-contract` developers.
 
-- **Breaking change** Bizinikiwi changed the `ContractExecResult` from `api.rpc.contracts.call`. The API does have pass-through support for both old and new variants via the `Contract` interface, however it means the structure has changed to accommodate the new Bizinikiwi structure. Refer to the [docs for the latest interface](https://js.pezkuwichain.app/docs/api-contract/start/contract.read) (including `isSuccess/isError` -> `isOk/isErr`, and the availability of the `gasConsumed`)
+- **Breaking change** Bizinikiwi changed the `ContractExecResult` from `api.rpc.contracts.call`. The API does have pass-through support for both old and new variants via the `Contract` interface, however it means the structure has changed to accommodate the new Bizinikiwi structure. Refer to the [docs for the latest interface](https://polkadot.js.org/docs/api-contract/start/contract.read) (including `isSuccess/isError` -> `isOk/isErr`, and the availability of the `gasConsumed`)
 
 Contributed:
 
@@ -3956,7 +3956,7 @@ Changes:
 
 ## 1.8.1 Mar 22, 2020
 
-- **Breaking change** The format for any custom RPCs have been changed (alongside API-internal changes) to allow for better RPC management. If you are currently using custom RPCs (or planning to do so), look at the [updated documentation](https://js.pezkuwichain.app/api/start/rpc.custom.html)
+- **Breaking change** The format for any custom RPCs have been changed (alongside API-internal changes) to allow for better RPC management. If you are currently using custom RPCs (or planning to do so), look at the [updated documentation](https://polkadot.js.org/api/start/rpc.custom.html)
 - **Breaking change** Alongside API RPC changes, the `@pezkuwi/jsonrpc` package has been removed. Since it was never documented and only used internally, this should not have adverse impacts. All RPC definitions itself has now been moved to the relevant modules inside `@pezkuwi/types/interfaces`
 - **Important** Bizinikiwi has an updated democracy module. If using an older chain add the `ReferendumInfo: 'ReferendumInfoTo239'` type when using referendums
 

README.md

@@ -10,7 +10,7 @@ This library provides a clean wrapper around all the methods exposed by a Pezkuw
 
 ## Documentation
 
-For complete documentation around the interfaces and their use, visit the [documentation portal](https://js.pezkuwichain.app/docs/api/).
+The API reference and a getting-started guide are at [developers.pezkuwichain.io](https://developers.pezkuwichain.io).
 
 ## Installation
 
@@ -48,7 +48,7 @@ console.log(`Connected to ${chain}`);
 
 ## Tutorials
 
-Looking for tutorials? Check out [examples](https://js.pezkuwichain.app/docs/api/examples/promise/) for guides on how to use the API to make queries and submit transactions.
+Looking for a walkthrough? [Getting started](https://developers.pezkuwichain.io/documents/Getting_started.html) connects, reads chain state, follows blocks and sends a transfer.
 
 ## Changelog
 
@@ -57,8 +57,8 @@ If you are an existing user, please track the [CHANGELOG](CHANGELOG.md) when cha
 ## Links
 
 - Website: https://pezkuwichain.io
-- Documentation: https://docs.pezkuwichain.io
-- API Docs: https://js.pezkuwichain.app
+- Developer docs: https://developers.pezkuwichain.io
+- Wiki: https://wiki.pezkuwichain.io
 - GitHub: https://github.com/pezkuwichain
 
 ## License

docs/404.html

@@ -1,12 +0,0 @@
-<!DOCTYPE html>
-<html>
-  <head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="initial-scale=0.5, maximum-scale=1">
-    <meta http-equiv="refresh" content="0;URL='https://polkadot.js.org/docs/api/'" />
-    <title>Redirecting to https://polkadot.js.org/docs/api/</title>
-  </head>
-  <body>
-    Redirecting to <a href="https://polkadot.js.org/docs/api/">https://polkadot.js.org/docs/api/</a>
-  </body>
-</html>

docs/getting-started.md

@@ -0,0 +1,111 @@
+---
+title: Getting started
+---
+
+# Getting started
+
+Every example on this page was run against the live PezkuwiChain network,
+except the final `signAndSend`, which needs a funded account. Each runs as an
+ES module (`node example.mjs`) on Node.js 18 or newer, and works the
+same way in a browser bundle.
+
+## Install
+
+```bash
+npm install @pezkuwi/api @pezkuwi/keyring
+```
+
+## Connect
+
+```js
+import { ApiPromise, WsProvider } from '@pezkuwi/api';
+
+const api = await ApiPromise.create({
+  provider: new WsProvider('wss://rpc.pezkuwichain.io')
+});
+
+const [chain, nodeName, nodeVersion] = await Promise.all([
+  api.rpc.system.chain(),
+  api.rpc.system.name(),
+  api.rpc.system.version()
+]);
+
+console.log(`Connected to ${chain} via ${nodeName} v${nodeVersion}`);
+```
+
+`ApiPromise.create` resolves once the API has fetched the runtime metadata, so
+from that point `api.query`, `api.tx` and `api.consts` reflect exactly what the
+connected chain supports.
+
+## Read chain state
+
+```js
+const header = await api.rpc.chain.getHeader();
+console.log(`Best block: #${header.number}`);
+
+const { tokenSymbol, tokenDecimals } = api.registry.getChainProperties().toHuman();
+console.log('Token:', tokenSymbol, 'decimals:', tokenDecimals); // [ 'HEZ' ] [ '12' ]
+
+const address = '5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty';
+const { data: { free } } = await api.query.system.account(address);
+console.log(`Free balance: ${free} TYR`);
+```
+
+HEZ has 12 decimals: 1 HEZ = 10^12 TYR. Balances come back in TYR, the smallest
+unit.
+
+## Follow new blocks
+
+```js
+const unsubscribe = await api.rpc.chain.subscribeNewHeads((head) => {
+  console.log(`New block #${head.number}`);
+});
+
+// later
+unsubscribe();
+```
+
+## Build, price and send a transfer
+
+```js
+import { Keyring } from '@pezkuwi/keyring';
+
+const keyring = new Keyring({ type: 'sr25519' });
+const sender = keyring.addFromUri('//Alice'); // a development key: never hold real funds with it
+
+const recipient = '5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty';
+const amount = 10n ** 12n; // 1 HEZ
+
+const tx = api.tx.balances.transferKeepAlive(recipient, amount);
+
+const { partialFee } = await tx.paymentInfo(sender);
+console.log(`Estimated fee: ${partialFee} TYR`);
+
+// Submitting needs a funded account:
+const unsub = await tx.signAndSend(sender, ({ status, dispatchError }) => {
+  if (dispatchError) {
+    console.error(dispatchError.toString());
+  }
+  if (status.isInBlock) {
+    console.log(`Included in block ${status.asInBlock}`);
+  }
+  if (status.isFinalized) {
+    unsub();
+  }
+});
+```
+
+`transferKeepAlive` refuses a transfer that would take the sender below the
+existential deposit and reap the account. Use `transferAllowDeath` only when
+that is what you want.
+
+## Disconnect
+
+```js
+await api.disconnect();
+```
+
+## Other networks
+
+The same code works against any endpoint listed on the [home page](index.md),
+for example `wss://asset-hub-rpc.pezkuwichain.io` for PezkuwiChain Asset Hub.

docs/index.html

@@ -1,12 +0,0 @@
-<!DOCTYPE html>
-<html>
-  <head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="initial-scale=0.5, maximum-scale=1">
-    <meta http-equiv="refresh" content="0;URL='https://polkadot.js.org/docs/api/'" />
-    <title>Redirecting to https://polkadot.js.org/docs/api/</title>
-  </head>
-  <body>
-    Redirecting to <a href="https://polkadot.js.org/docs/api/">https://polkadot.js.org/docs/api/</a>
-  </body>
-</html>

docs/index.md

@@ -0,0 +1,46 @@
+# Pezkuwi API
+
+`@pezkuwi/api` is the JavaScript and TypeScript library for talking to PezkuwiChain
+and other Bizinikiwi-based networks. Your application loads it and connects
+straight to a node's RPC endpoint: there is no server in between.
+
+- New here? Start with [Getting started](getting-started.md).
+- Looking for a class or a method? Use the search box, or browse the packages below.
+
+## Install
+
+```bash
+npm install @pezkuwi/api
+```
+
+## Packages
+
+| Package | What it does |
+|---|---|
+| `@pezkuwi/api` | `ApiPromise` and `ApiRx`, the entry points most applications use |
+| `@pezkuwi/api-base` | The base class both APIs share |
+| `@pezkuwi/api-derive` | Derived queries that combine several storage reads into one answer |
+| `@pezkuwi/api-contract` | Deploying and calling ink! smart contracts |
+| `@pezkuwi/rpc-core` | The typed JSON-RPC layer |
+| `@pezkuwi/rpc-provider` | `WsProvider`, `HttpProvider` and the light-client provider |
+| `@pezkuwi/types` | The runtime type registry and every chain type |
+| `@pezkuwi/types-codec` | SCALE codec primitives (`Struct`, `Enum`, `Vec`, `Compact`, …) |
+| `@pezkuwi/types-create` | Building types from their definitions |
+
+Keys and signing live in `@pezkuwi/keyring`, and hashing and address helpers in
+`@pezkuwi/util-crypto`. Both come from the
+[pezkuwi-common](https://github.com/pezkuwichain/pezkuwi-common) repository.
+
+## Public endpoints
+
+| Network | WebSocket RPC |
+|---|---|
+| PezkuwiChain relay | `wss://rpc.pezkuwichain.io` |
+| PezkuwiChain Asset Hub | `wss://asset-hub-rpc.pezkuwichain.io` |
+| Zagros Asset Hub (test network) | `wss://zagros-asset-hub-rpc.pezkuwichain.io` |
+
+## Source
+
+The code is at [github.com/pezkuwichain/pezkuwi-api](https://github.com/pezkuwichain/pezkuwi-api).
+This reference is generated from it, so what you read here is what the published
+packages contain.

package.json

@@ -32,6 +32,7 @@
     "build:upgrades": "pezkuwi-dev-run-test upgrades/e2e",
     "chain:info": "pezkuwi-types-chain-info",
     "clean": "pezkuwi-dev-clean-build",
+    "docs": "typedoc",
     "lint": "pezkuwi-dev-run-lint",
     "postinstall": "pezkuwi-dev-yarn-only",
     "test": "pezkuwi-dev-run-test --env node ^e2e",
@@ -44,7 +45,8 @@
     "@pezkuwi/dev-ts": "^0.86.3",
     "@pezkuwi/typegen": "workspace:*",
     "@types/node": "^22.10.5",
-    "@types/yargs": "^17.0.35"
+    "@types/yargs": "^17.0.35",
+    "typedoc": "0.28.20"
   },
   "resolutions": {
     "@isaacs/nonrecursive-glob-match@npm:^1.0.1": "1.0.1",

packages/api/README.md

@@ -7,13 +7,13 @@ The API wrappers provide a standard interface for use -
 - A static `.create(<optional ApiOptions>)` that returns an API instance when connected, decorated and ready-to use. ApiOptions can include an optional WsProvider and optional custom type definitions `{ provider: <Optional WsProvider>, types: <Optional RegistryTypes> }`.
 - The above is just a wrapper for `new Api(<optional ApiOptions>) `, exposing the `isReady` getter
 - `api.rpc.<section>.<method>` provides access to actual RPC calls, be it for queries, submission or retrieving chain information
-  - [RPC (node interface)](https://js.pezkuwichain.app/docs/bizinikiwi/rpc)
+  - browse them live in the [Pezkuwi Portal, RPC calls](https://js.pezkuwichain.io/#/rpc)
 - `api.query.<section>.<method>` provides access to chain state queries. These are dynamically populated based on what the runtime provides
-  - [Storage chain state (runtime node interface)](https://js.pezkuwichain.app/docs/bizinikiwi/storage)
+  - browse them live in the [Pezkuwi Portal, chain state](https://js.pezkuwichain.io/#/chainstate)
 - `api.tx.<section>.<method>` provides the ability to create a transaction, like chain state, this list is populated from a runtime query
-  - [Extrinsics (runtime node interface)](https://js.pezkuwichain.app/docs/bizinikiwi/extrinsics)
+  - browse them live in the [Pezkuwi Portal, extrinsics](https://js.pezkuwichain.io/#/extrinsics)
 - `api.consts.<section>.<constant>` provides access to the module constants (parameter types).
-  - [Constants (runtime node interface)](https://js.pezkuwichain.app/docs/bizinikiwi/constants)
+  - browse them live in the [Pezkuwi Portal, constants](https://js.pezkuwichain.io/#/chainstate/constants)
 
 ## API Selection
 

tsconfig.eslint.json

@@ -11,7 +11,8 @@
     "scripts/*",
     ".prettierrc.cjs",
     "eslint.config.js",
-    "rollup.config.js"
+    "rollup.config.js",
+    "typedoc.config.mjs"
   ],
   "exclude": [
     "**/node_modules/**/*",

typedoc.config.mjs

@@ -0,0 +1,54 @@
+// Copyright 2017-2026 @pezkuwi/api authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+// The API reference published at developers.pezkuwichain.io. `yarn docs` writes it
+// to build-docs/ (ignored by git); CI builds it on every pull request.
+
+import { OptionDefaults } from 'typedoc';
+
+/** @type {Partial<import('typedoc').TypeDocOptions>} */
+const config = {
+  entryPointStrategy: 'packages',
+  entryPoints: [
+    'packages/api',
+    'packages/api-base',
+    'packages/api-contract',
+    'packages/api-derive',
+    'packages/rpc-core',
+    'packages/rpc-provider',
+    'packages/types',
+    'packages/types-codec',
+    'packages/types-create'
+  ],
+  excludePrivate: true,
+  hostedBaseUrl: 'https://developers.pezkuwichain.io/',
+  name: 'Pezkuwi API',
+  navigationLinks: {
+    GitHub: 'https://github.com/pezkuwichain/pezkuwi-api',
+    npm: 'https://www.npmjs.com/package/@pezkuwi/api'
+  },
+  out: 'build-docs',
+  // Each package.json points at its build output; the reference is built from src/.
+  packageOptions: {
+    entryPoints: ['src/index.ts'],
+    readme: 'none',
+    skipErrorChecking: true
+  },
+  projectDocuments: [
+    'docs/getting-started.md'
+  ],
+  readme: 'docs/index.md',
+  skipErrorChecking: true,
+  tsconfig: 'tsconfig.build.json'
+};
+
+// The sources use tags TypeDoc does not define: @description on most members,
+// @name on derives, @noInheritDoc and @constructor on some classes. Declaring
+// them keeps their text in the reference instead of a warning per use.
+// Each package is converted with packageOptions, so the tags go there as well.
+for (const target of [config, config.packageOptions]) {
+  target.blockTags = [...OptionDefaults.blockTags, '@description', '@describe', '@name'];
+  target.modifierTags = [...OptionDefaults.modifierTags, '@noInheritDoc', '@constructor'];
+}
+
+export default config;

yarn.lock

@@ -458,6 +458,19 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@gerrit0/mini-shiki@npm:^3.23.0":
+  version: 3.23.0
+  resolution: "@gerrit0/mini-shiki@npm:3.23.0"
+  dependencies:
+    "@shikijs/engine-oniguruma": "npm:^3.23.0"
+    "@shikijs/langs": "npm:^3.23.0"
+    "@shikijs/themes": "npm:^3.23.0"
+    "@shikijs/types": "npm:^3.23.0"
+    "@shikijs/vscode-textmate": "npm:^10.0.2"
+  checksum: 10/d44dac7c3f58ba136285b3c15c8a89eba120f7a493dddcf6178601ab8c0a5286da6a19515100297934288c41ae225f21013a4c395fe2f656b58f812dd13ccc1e
+  languageName: node
+  linkType: hard
+
 "@humanfs/core@npm:^0.19.2":
   version: 0.19.2
   resolution: "@humanfs/core@npm:0.19.2"
@@ -2148,6 +2161,51 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@shikijs/engine-oniguruma@npm:^3.23.0":
+  version: 3.23.0
+  resolution: "@shikijs/engine-oniguruma@npm:3.23.0"
+  dependencies:
+    "@shikijs/types": "npm:3.23.0"
+    "@shikijs/vscode-textmate": "npm:^10.0.2"
+  checksum: 10/edd8983be86f6b055793813e80ecf31c3cefdd896f3742797ae03f2cbb9f467ac736c4b152d4a5c42dbd17da17d24ff798a15d37bcf6205d7f8cd8f44e2a11e0
+  languageName: node
+  linkType: hard
+
+"@shikijs/langs@npm:^3.23.0":
+  version: 3.23.0
+  resolution: "@shikijs/langs@npm:3.23.0"
+  dependencies:
+    "@shikijs/types": "npm:3.23.0"
+  checksum: 10/115b1afb9eb4eb300eb68b146e442f7e6d196878798c5b9d75dd53a6ef1e1c3b27e325353a10973e3fa47d88630e937b8a3cf3b37b6eef80bf2aec3d51657bb3
+  languageName: node
+  linkType: hard
+
+"@shikijs/themes@npm:^3.23.0":
+  version: 3.23.0
+  resolution: "@shikijs/themes@npm:3.23.0"
+  dependencies:
+    "@shikijs/types": "npm:3.23.0"
+  checksum: 10/741987380445b788aea6cc1e03492bc06950f1a0461edf45083bd226889c5ba78c7ed1af9724afacab7d6471777f0c0e8871577183dfb2cfbceb255663374835
+  languageName: node
+  linkType: hard
+
+"@shikijs/types@npm:3.23.0, @shikijs/types@npm:^3.23.0":
+  version: 3.23.0
+  resolution: "@shikijs/types@npm:3.23.0"
+  dependencies:
+    "@shikijs/vscode-textmate": "npm:^10.0.2"
+    "@types/hast": "npm:^3.0.4"
+  checksum: 10/18b5703d445d53dd6782a3e2c7332009302c6c046f301d9cd99f1a26b9c8329b3e502b096894bffac61f78835c533827bab2ce78a39666ab87b78f8d7ca11f7b
+  languageName: node
+  linkType: hard
+
+"@shikijs/vscode-textmate@npm:^10.0.2":
+  version: 10.1.0
+  resolution: "@shikijs/vscode-textmate@npm:10.1.0"
+  checksum: 10/7cf3d9c4c17979d680e670a985cd3e166a1e9960e6d648c3dc60299812040639a90b1dc9e7ab43bd24057a2913a122133fafde3d2cadeff515ebedca18a53fcd
+  languageName: node
+  linkType: hard
+
 "@stylistic/eslint-plugin@npm:^5.10.0":
   version: 5.10.0
   resolution: "@stylistic/eslint-plugin@npm:5.10.0"
@@ -2345,6 +2403,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/hast@npm:^3.0.4":
+  version: 3.0.5
+  resolution: "@types/hast@npm:3.0.5"
+  dependencies:
+    "@types/unist": "npm:*"
+  checksum: 10/864a274e6e5ce0662de3bf984d804aea1f0e64eb4d5ffed27d9e832ee0002e76dfa18f1812a96b7cc24e2a9f40125ff2e47f73f7ab90c815840047c197d89635
+  languageName: node
+  linkType: hard
+
 "@types/http-errors@npm:*":
   version: 2.0.5
   resolution: "@types/http-errors@npm:2.0.5"
@@ -2426,6 +2493,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/unist@npm:*":
+  version: 3.0.3
+  resolution: "@types/unist@npm:3.0.3"
+  checksum: 10/96e6453da9e075aaef1dc22482463898198acdc1eeb99b465e65e34303e2ec1e3b1ed4469a9118275ec284dc98019f63c3f5d49422f0e4ac707e5ab90fb3b71a
+  languageName: node
+  linkType: hard
+
 "@types/ws@npm:^8.18.1":
   version: 8.18.2
   resolution: "@types/ws@npm:8.18.2"
@@ -4210,6 +4284,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"entities@npm:^4.5.0":
+  version: 4.5.0
+  resolution: "entities@npm:4.5.0"
+  checksum: 10/ede2a35c9bce1aeccd055a1b445d41c75a14a2bb1cd22e242f20cf04d236cdcd7f9c859eb83f76885327bfae0c25bf03303665ee1ce3d47c5927b98b0e3e3d48
+  languageName: node
+  linkType: hard
+
 "entities@npm:^6.0.0":
   version: 6.0.1
   resolution: "entities@npm:6.0.1"
@@ -6422,6 +6503,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"linkify-it@npm:^5.0.2":
+  version: 5.0.2
+  resolution: "linkify-it@npm:5.0.2"
+  dependencies:
+    uc.micro: "npm:^2.0.0"
+  checksum: 10/1d23387319c15f2c3d41cdada0fc2edac73afb6083e967ee051afc826f7d8d9f920e287fb7c32679b4516f60e6450853dee2b4339d7d2f313222e4b9e5be1476
+  languageName: node
+  linkType: hard
+
 "loader-runner@npm:^4.3.1":
   version: 4.3.1
   resolution: "loader-runner@npm:4.3.1"
@@ -6491,6 +6581,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"lunr@npm:^2.3.9":
+  version: 2.3.9
+  resolution: "lunr@npm:2.3.9"
+  checksum: 10/f2f6db34c046f5a767782fe2454e6dd69c75ba3c5cf5c1cb9cacca2313a99c2ba78ff8fa67dac866fb7c4ffd5f22e06684793f5f15ba14bddb598b94513d54bf
+  languageName: node
+  linkType: hard
+
 "madge@npm:^8.0.0":
   version: 8.0.0
   resolution: "madge@npm:8.0.0"
@@ -6564,6 +6661,22 @@ __metadata:
   languageName: node
   linkType: hard
 
+"markdown-it@npm:^14.3.0":
+  version: 14.3.3
+  resolution: "markdown-it@npm:14.3.3"
+  dependencies:
+    argparse: "npm:^2.0.1"
+    entities: "npm:^4.5.0"
+    linkify-it: "npm:^5.0.2"
+    mdurl: "npm:^2.0.0"
+    punycode.js: "npm:^2.3.1"
+    uc.micro: "npm:^2.1.0"
+  bin:
+    markdown-it: bin/markdown-it.mjs
+  checksum: 10/ab96ec39766d59ed234304ef01108a13793b735dc1032a00f5bd89a20fb030f8c9305ac7b76f1f59a10257a4e456cdffd5f7c568e6ef9d99fe7f1fe2074395df
+  languageName: node
+  linkType: hard
+
 "math-intrinsics@npm:^1.1.0":
   version: 1.1.0
   resolution: "math-intrinsics@npm:1.1.0"
@@ -6571,6 +6684,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"mdurl@npm:^2.0.0":
+  version: 2.1.0
+  resolution: "mdurl@npm:2.1.0"
+  checksum: 10/b7db2c0aa0479e11c5454b8a6ae055326bd9180b83e58696f89e862b84a0f5c7c80e497be650f205c0807b4567f6ee3e09238a76c8f1217f1fd750a1f6f2146d
+  languageName: node
+  linkType: hard
+
 "media-typer@npm:^1.1.0":
   version: 1.1.1
   resolution: "media-typer@npm:1.1.1"
@@ -7472,6 +7592,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"punycode.js@npm:^2.3.1":
+  version: 2.3.1
+  resolution: "punycode.js@npm:2.3.1"
+  checksum: 10/f0e946d1edf063f9e3d30a32ca86d8ff90ed13ca40dad9c75d37510a04473340cfc98db23a905cc1e517b1e9deb0f6021dce6f422ace235c60d3c9ac47c5a16a
+  languageName: node
+  linkType: hard
+
 "punycode@npm:^2.1.0, punycode@npm:^2.1.1, punycode@npm:^2.3.1":
   version: 2.3.1
   resolution: "punycode@npm:2.3.1"
@@ -7955,6 +8082,7 @@ __metadata:
     "@pezkuwi/typegen": "workspace:*"
     "@types/node": "npm:^22.10.5"
     "@types/yargs": "npm:^17.0.35"
+    typedoc: "npm:0.28.20"
   languageName: unknown
   linkType: soft
 
@@ -8940,6 +9068,23 @@ __metadata:
   languageName: node
   linkType: hard
 
+"typedoc@npm:0.28.20":
+  version: 0.28.20
+  resolution: "typedoc@npm:0.28.20"
+  dependencies:
+    "@gerrit0/mini-shiki": "npm:^3.23.0"
+    lunr: "npm:^2.3.9"
+    markdown-it: "npm:^14.3.0"
+    minimatch: "npm:^10.2.5"
+    yaml: "npm:^2.9.0"
+  peerDependencies:
+    typescript: 5.0.x || 5.1.x || 5.2.x || 5.3.x || 5.4.x || 5.5.x || 5.6.x || 5.7.x || 5.8.x || 5.9.x || 6.0.x
+  bin:
+    typedoc: bin/typedoc
+  checksum: 10/947172bc1bd85333aab1c6fb9dfe925e9184fcca6c6cd7310588e7d2135efcd4c412dcf9eb495c34522d3efdc793c2bc9e58d7ea06b1f917abffb7494ae04ec7
+  languageName: node
+  linkType: hard
+
 "typescript@npm:5.5.4":
   version: 5.5.4
   resolution: "typescript@npm:5.5.4"
@@ -8960,6 +9105,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"uc.micro@npm:^2.0.0, uc.micro@npm:^2.1.0":
+  version: 2.1.0
+  resolution: "uc.micro@npm:2.1.0"
+  checksum: 10/37197358242eb9afe367502d4638ac8c5838b78792ab218eafe48287b0ed28aaca268ec0392cc5729f6c90266744de32c06ae938549aee041fc93b0f9672d6b2
+  languageName: node
+  linkType: hard
+
 "uglify-js@npm:^3.1.4":
   version: 3.19.3
   resolution: "uglify-js@npm:3.19.3"
@@ -9593,6 +9745,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"yaml@npm:^2.9.0":
+  version: 2.9.1
+  resolution: "yaml@npm:2.9.1"
+  bin:
+    yaml: bin.mjs
+  checksum: 10/123c5e56a26f4962d3d5954971b2071a533d17041e00ae9ff6a5e634aed2503639bbdeea143b1610eac29613aad95a3a1d10f5fbda87b92203c039ce63934295
+  languageName: node
+  linkType: hard
+
 "yargs-parser@npm:^21.1.1":
   version: 21.1.1
   resolution: "yargs-parser@npm:21.1.1"