feat: update codegen with latest changes

docs/pages/codegen.md

@@ -20,16 +20,19 @@ Options:
   -f, --file <filename>       Source from metadata encoded file
   -w, --wsUrl <URL>           Source from websocket URL
   -c, --chainSpec <filename>  Source from chain spec file
-  -n, --name <name>           Source from a well-known chain (choices: "polkadot", "ksmcc3", "rococo_v2_2", "westend2")
+  -n, --name <name>           Source from a well-known chain (choices: "ksmcc3", "paseo",
+                              "polkadot", "polkadot_collectives", "rococo_v2_2", "westend2", [...]")
+  --wasm <filename>           Source from runtime wasm file
   --no-persist                Do not persist the metadata as a file
+  --skip-codegen              Skip running codegen after adding
   -h, --help                  display help for command
 ```
 
-`papi add` registers a new chain. It requires a key, which is the JS variable name the codegen will create, and a source (`-f`, `-w`, `-c`, or `-n`). The command stores this information for later use into a configuration file `polkadot-api.json` and then downloads the fresh metadata into a file `${key}.scale`.
+`papi add` registers a new chain. It requires a key, which is the name of the constant the codegen will create, and a source (`-f`, `-w`, `-c`, `-n`, or `--wasm`). The command download the fresh metadata for that chain and stores this information for later use into a `.papi` folder, with a configuration file `polkadot-api.json` and the metadata file `${key}.scale`.
 
 You can add as many chains as you want, but each has to have a unique `key` (which must be a valid JS variable name).
 
-The CLI can then be used to generate the type descriptors for all of the added chains through the `generate` command.
+`papi add` by default runs codegen automatically. If you want to add multiple chains without having to rerun codegen, you can use the flag `--skip-codegen`, and then run `papi generate` command once you want to run the codegen.
 
 ```sh
 npx papi generate
@@ -49,10 +52,14 @@ It's recommended to add `papi` to the `postinstall` script in package.json to ha
 }
 ```
 
-The code is generated into the `@polkadot-api/descriptors` node modules package
+The code is generated into a [local package](https://docs.npmjs.com/cli/v9/configuring-npm/package-json/#local-paths) located in `.papi/descriptors`, which gets installed as a regular `@polkadot-api/descriptors` node modules package.
+
+The folder `.papi` should be added to your source control repository. The only thing that should be ignored are the generated files from the codegen (`.papi/descriptors/dist`), but for git, that's already ignored by a pre-configured `.gitignore` inside `.papi`.
+
+When the metadata is updated, the codegen will update the generated code and also the package version, to have package managers update the `@polkadot-api/descriptors` package.
 
 :::info
-Some package managers clean the `node_modules` folder after installing or removing dependencies. When that happens, run the codegen again.
+If you're using yarn v1, you might need to run `yarn --force` after a codegen for it to detect the change.
 :::
 
 ## Contents
@@ -67,11 +74,13 @@ The generated code contains all of the types extracted from the metadata of all
   - Constants
 - Every runtime call
 
-These are consumed by `getTypedApi()`, which allows the IDE to reference any of these calls with autocompletion, etc. At runtime, it also contains the checksum of each of these calls, so that it can detect incompatibilities with the chain it's connected to.
+These are consumed by `getTypedApi()`, which allows the IDE to reference any of these calls with autocompletion, etc. At runtime, it also contains a representation of the type for each of these calls, so that it can detect incompatibilities with the chain it's connected to.
 
 The types are anonymous (they don't have a name in the metadata), but PolkadotAPI has a directory of well-known types for some of the most widely used Enums. If a chain is using one of these well-known types, it's also generated and exported.
 
-In the event that there are two chains with the two well-known types that have the same name but they are different, then the key is appended at the beginning of the type. For instance, if two chains `dot` and `ksm` might have a slightly different `PreimageRequestStatus`, in that case, the codegen exports `DotPreimageRequestStatus` and `KsmPreimageRequestStatus`.
+:::warning
+It's important to know that the descriptors exported by the codegen **should be treated as a black box**. When importing the descriptors of a chain, the type might not actually match what's in runtime, and its internals are subject to change. It has to be treated as an opaque token, passing it directly to `.getTypedApi()`.
+:::
 
 ## Usage
 

docs/pages/getting-started.mdx

@@ -2,10 +2,10 @@ import * as Tabs from "../components/Tabs"
 
 # Getting Started
 
-Start by installing `polkadot-api` and `@polkadot-api/descriptors`
+Start by installing `polkadot-api`
 
 ```sh
-npm i polkadot-api @polkadot-api/descriptors
+npm i polkadot-api
 ```
 
 Next, download the latest metadata from the chain you want to connect to and generate the types: