feat: update docs for pop with latest changes

pop-cli-for-appchains/SUMMARY.md

@@ -16,6 +16,7 @@
   * [Create an EVM parachain](guides/create-a-new-parachain/create-an-evm-parachain.md)
 * [Benchmarking](guides/benchmarking/benchmarking-pallets-and-extrinsics.md)
 * [Build](guides/build-your-parachain.md)
+  * [Build your chain specification](guides/build-spec.md)
   * [Build your runtime deterministically](guides/build-deterministic-runtime.md)
 * [Call](guides/call-a-chain.md)
 * [Deploy](guides/launch-a-chain/README.md)

pop-cli-for-appchains/guides/build-deterministic-runtime.md

@@ -4,17 +4,29 @@ description: The following guide shows how to build deterministic runtimes.
 
 # Build your runtime deterministically
 
-By default, the Rust compiler generates optimized Wasm binaries, but they aren't always deterministically reproducible. If the Wasm runtime isn't deterministic, each build might produce slightly different bytecode, This can be a problem for blockchain networks where every node must run the exact same runtime.
+> Note: Omni-node-based chains typically ship only a runtime and rely on the community `polkadot-omni-node` host. In
+> that setup, building your runtime deterministically is especially important since there is no bespoke node binary — the
+> runtime is the source of truth. Pop can automatically source `polkadot-omni-node` when needed.
 
-To ensure deterministic Substrate runtime builds, Pop CLI integrates [SRTool (Substrate Runtime Toolbox)](https://github.com/paritytech/srtool). `SRTool` guarantees that every runtime build produces identical Wasm bytecode, making it reliable for production use. This build requires [Docker](https://www.docker.com/) or [Podman](https://podman.io/) to be installed and running. Pop CLI automatically invokes the `SRTool` image to generate a reproducible and verifiable runtime.
+By default, the Rust compiler generates optimized Wasm binaries, but they aren't always deterministically reproducible.
+If the Wasm runtime isn't deterministic, each build might produce slightly different bytecode, This can be a problem for
+blockchain networks where every node must run the exact same runtime.
+
+To ensure deterministic Substrate runtime builds, Pop CLI
+integrates [SRTool (Substrate Runtime Toolbox)](https://github.com/paritytech/srtool). `SRTool` guarantees that every
+runtime build produces identical Wasm bytecode, making it reliable for production use. This build
+requires [Docker](https://www.docker.com/) or [Podman](https://podman.io/) to be installed and running. Pop CLI
+automatically invokes the `SRTool` image to generate a reproducible and verifiable runtime.
 
 This guide provides a quick overview of the importance of deterministic builds and how to achieve them using Pop CLI:
 
 ## Build a deterministic runtime with Pop CLI
 
-While generating your chain spec with `pop build spec`, Pop CLI also gives you the option to build your runtime deterministically and inject it automatically.
+While generating your chain spec with `pop build spec`, Pop CLI also gives you the option to build your runtime
+deterministically and inject it automatically.
 
-Once you select the option to build deterministically, Pop CLI will prompt you to provide the runtime path (by default it's typically located in the runtime/ folder). After confirming, the deterministic build process will begin.
+Once you select the option to build deterministically, Pop CLI will prompt you to provide the runtime path (by default
+it's typically located in the runtime/ folder). After confirming, the deterministic build process will begin.
 
 > ⏳ The build may take 10–15 minutes or more, depending on your setup, so be patient!
 
@@ -37,9 +49,21 @@ Once the build is complete, Pop CLI will automatically inject the resulting runt
 If you'd prefer not to be prompted interactively, you can specify everything up front via command line:
 
 ```
+# minimal deterministic build example
 pop build spec --deterministic --runtime ./runtime/mainnet
+
+# optionally, specify the runtime package name used by srtool (if your workspace layout differs)
+# note: --package is only applicable when --deterministic is set
+pop build spec --deterministic --runtime ./runtime/mainnet --package parachain-template-runtime
 ```
 
+Notes about flags:
+
+- You can pass `--runtime` without `--deterministic` to pre-select the runtime directory for the command. This alone
+  will not trigger a deterministic build; you must add `--deterministic` to enable srtool.
+- The `--package` flag is available to explicitly set the runtime package name when doing a deterministic build; if
+  omitted, Pop CLI will infer it from the runtime directory.
+
 ## Resources
 
 #### Learning Resources

pop-cli-for-appchains/guides/build-spec.md

@@ -0,0 +1,108 @@
+---
+description: Generate a plain chain specification and optional artifacts for your chain.
+---
+
+# Build you Chain Spec
+
+The chain specification ("chain spec") captures the initial state and configuration of your chain. Nodes use it to start
+a network or to join and sync with an existing one. With Pop CLI you can generate a plain chain spec interactively or
+non‑interactively, and optionally produce extra artifacts such as genesis state and wasm code, and even inject a
+deterministically built runtime.
+
+## Interactive walkthrough
+
+Run the command without arguments to be guided through all choices:
+
+```bash
+pop build spec
+```
+
+This will prompt you for key values like output file name, parachain id, relay chain, chain type, protocol id,
+properties, whether to generate genesis files, and whether to build and inject a deterministic runtime.
+
+<figure><img src="../.gitbook/assets/build_spec.gif" alt="pop build spec"><figcaption></figcaption></figure>
+
+> Tip: You can press Tab to accept defaults and type to filter list selections.
+
+### What you’ll typically provide
+
+- Output file name/path for the plain spec (default: ./chain-spec.json)
+- Parachain ID (default: 2000)
+- Chain type (Development / Local / Live)
+- Relay chain (paseo, westend, kusama, polkadot and their local variants)
+- Protocol ID and optional properties (token symbol/decimals/SS58)
+- Whether to also generate genesis state and genesis code files
+- Optional: Build the runtime deterministically and inject it into the spec
+
+## Non‑interactive usage
+
+Prefer to skip prompts? Provide flags up front.
+
+```bash
+# Minimal example: write a plain chain spec
+pop build spec -o ./chain-spec.json
+
+# Provide basics explicitly
+pop build spec -o ./chain-spec.json \
+  --id 2000 \
+  --type Local \
+  --relay paseo \
+  --protocol-id my-protocol \
+  --properties "tokenSymbol=UNIT,decimals=12"
+
+# Include build profile, features, and skip building binaries (if already built)
+pop build spec -o ./chain-spec.json \
+  --profile release \
+  --features foo,bar \
+  --skip-build
+
+# Also generate genesis state and wasm code files alongside the spec
+pop build spec -o ./chain-spec.json \
+  --genesis-state \
+  --genesis-code
+```
+
+### Deterministic runtime build and injection (optional)
+
+Pop CLI can build your runtime deterministically using srtool and inject the resulting wasm code into the chain spec
+generation flow.
+
+```bash
+# Minimal deterministic build example
+pop build spec --deterministic --runtime ./runtime/mainnet
+
+# Optionally specify the runtime package name used by srtool
+# note: --package is only applicable when --deterministic is set
+pop build spec --deterministic --runtime ./runtime/mainnet --package parachain-template-runtime
+```
+
+Notes about flags:
+
+- You can now pass --runtime without --deterministic to pre-select the runtime directory for the command. This alone
+  will not trigger a deterministic build you must add --deterministic to enable srtool.
+- The --package flag is available to explicitly set the runtime package name when doing a deterministic build; if
+  omitted, Pop CLI will infer it from the runtime directory.
+
+> [!TIP]
+> Omni-node-based chains: If your chain uses the community `polkadot-omni-node` host (ships only a runtime), you can still
+use `pop build spec` the same way. Deterministic builds are recommended; Pop can also auto-source the
+`polkadot-omni-node` binary when needed in related workflows.
+
+## Outputs
+
+Depending on the flags used you’ll get:
+
+- A plain chain spec JSON.
+- Optionally, a raw chain spec JSON.
+- Optionally, a genesis state file.
+- Optionally, a genesis wasm code file.
+
+
+#### Learning Resources
+
+- 🧑‍🏫 Background on Polkadot/Parachains: wiki.polkadot.network
+- 🧑‍🔧 srtool: https://github.com/paritytech/srtool
+
+**Need help?**
+
+Ask on Polkadot Stack Exchange (tag it `pop`) or drop by our Telegram: https://t.me/onpopio. We're here to help!

pop-cli-for-appchains/guides/build-your-parachain.md

@@ -7,10 +7,6 @@ cd my-appchain
 pop build
 ```
 
-{% hint style="info" %}
-For Pop CLI versions <`0.3.0` the `pop build` command is `pop build parachain`
-{% endhint %}
-
 ```
 ┌   Pop CLI : Building a parachain
 │
@@ -27,10 +23,6 @@ If you are outside the project's directory, you can specify the path
 pop build -p ./my-appchain
 ```
 
-{% hint style="info" %}
-For Pop CLI versions <`0.3.0` the `pop build` command is `pop build parachain`
-{% endhint %}
-
 If you are building the parachain with the intent to onboard the parachain to a Polkadot Relay chain then you can run the following build command:
 
 ```

pop-cli-for-appchains/guides/call-a-chain.md

@@ -8,45 +8,112 @@ Interact with a chain **using** Pop CLI's interactive guidance by simply enterin
 pop call chain
 ```
 
-You will be prompted to select a pallet, the dispatchable function and its required arguments, connection details for the chain, and the account to sign the transaction.
+First, you will be prompted to select which chain you want to interact with from a list of available chains. You can *
+*type to filter** the list and quickly find your desired chain. If you want to connect to a custom RPC endpoint, select
+the **"Custom"** option, which allows you to manually type the chain URL.
 
-<figure><img src="../.gitbook/assets/callchain.gif" alt="pop call chain"><figcaption><p>pop call chain</p></figcaption></figure>
+After selecting your chain, you will be prompted to select a pallet, then choose what you want to do with that pallet:
+
+- **Execute an extrinsic** (dispatchable function)
+- **Query storage** items
+- **Read constant** values
+
+After making your selection, you'll be guided through providing any required arguments and (for extrinsics) the account
+to sign the transaction.
+
+### What Can You Do?
+
+The `pop call chain` command supports three types of operations:
+
+#### 1. Execute Extrinsics
+
+Submit transactions to the chain by calling dispatchable functions. These require signing and will modify chain state.
+
+#### 2. Query Storage
+
+Read storage items from the chain's state. Storage queries don't require signing and can read:
+
+- **Plain storage values** (e.g., System::Number - the current block number)
+- **Storage maps** (e.g., System::Account - account information by address)
+
+#### 3. Read Constants
+
+Access constant values defined in the runtime metadata (e.g., System::Version, System::BlockHashCount).
 
 ### Manual (non-interactive)
 
 If you prefer not to use interactive prompts, you can call the chain by specifying all the required arguments directly:
 
+#### Executing an Extrinsic
+
+You can execute an extrinsic by specifying the pallet and function (dispatchable function name) and any arguments.
+
+> [!TIP]
+> If you receive "Pallet not found" or "Function not found" errors, double-check the case of your pallet and function
+> names. Common examples: use "Balances" (not "balances"), "transfer_keep_alive" (not "transferKeepAlive").
+
 ```shell
-pop call chain --pallet System --function remark --args "0x11" --url ws://localhost:9944/ --suri //Alice --skip-confirm
+pop call chain --pallet System --function remark --args "0x11" --url ws://localhost:9944 --suri //Alice --sudo
 ```
 
+<img src="../.gitbook/assets/callchain_extrinsic.gif" alt="pop call chain">
+
+#### Querying Storage
+
+You can query storage items by specifying the pallet and function (storage item name).
+Storage queries return the current value immediately without requiring transaction signing.
+
+```shell
+pop call chain --pallet Sudo --function Key --url wss://pas-rpc.stakeworld.io -y
 ```
-┌   Pop CLI : Call a chain
-│
-◇  Would you like to dispatch this function call with `Root` origin?
-│  No 
-│
-⚙  pop call chain --pallet System --function remark --args "0x11" --url ws://localhost:9944/ --suri //Alice
-│  
-⚙  Encoded call data: 0x00000411
-│  
-◇  Do you want to submit the extrinsic?
-│  Yes 
-│
-◇  Extrinsic submitted with hash: "0xadbfbb2f92b22a2c5d6542ba80e4111b5c60057f594a6d155341879c5a46f96e"
-│
-└  Call complete.
+
+```shell
+pop call chain --pallet System --function Account --args 0xb815821c5b300d1667d5fc081c06cc4b6addffb90464d68d871ee363b01a127c --url wss://pas-rpc.stakeworld.io -y
 ```
 
-#### Additional Options
+<img src="../.gitbook/assets/callchain_state.gif" alt="pop call chain">
+
+#### Reading Constants
 
-* To dispatch a call with Root origin when the chain's runtime includes `pallet-sudo`, you can wrap the call in a `sudo.sudo()` call by using the `--sudo` flag:
+Query constant values from the runtime.
+Constants are read directly from metadata and don't require signing or keys.
 
 ```shell
-pop call chain --pallet System --function remark --args "0x11" --url ws://localhost:9944/ --suri //Alice --sudo
+pop call chain --pallet System --function Version --url wss://pas-rpc.stakeworld.io -y
 ```
 
-* If you already have the SCALE-encoded call data, and want to directly submit the extrinsic:
+```shell
+pop call chain --pallet System --function BlockHashCount --url wss://pas-rpc.stakeworld.io -y
+```
+
+### Additional Options
+
+#### Sudo Calls
+
+To dispatch a call with Root origin when the chain's runtime includes `pallet-sudo`, you can wrap the call in a
+`sudo.sudo()` call by using the `--sudo` flag:
+
+```shell
+pop call chain --pallet System --function remark --args "0x11" --url ws://localhost:9944 --suri //Alice --sudo
+```
+
+#### Using Wallet for Signing
+
+You can use a browser extension wallet to sign extrinsics instead of providing a secret URI:
+
+```shell
+pop call chain --pallet System --function remark --args "0x11" --url ws://localhost:9944/ --use-wallet
+```
+
+Or use the shorthand `-w`:
+
+```shell
+pop call chain --pallet System --function remark --args "0x11" --url ws://localhost:9944/ -w
+```
+
+#### Direct Call Data Submission
+
+If you already have the SCALE-encoded call data and want to directly submit the extrinsic:
 
 ```shell
 pop call chain --call 0x00000411 --url ws://localhost:9944/ --suri //Alice
@@ -65,6 +132,65 @@ pop call chain --call 0x00000411 --url ws://localhost:9944/ --suri //Alice
 └  Call complete.
 ```
 
+#### Skip Confirmation
+
+Use the `--skip-confirm` or `-y` flag to automatically submit extrinsics without prompting for confirmation. This also
+prevents the prompt to perform another call:
+
+```shell
+pop call chain --pallet System --function remark --args "0x11" --url ws://localhost:9944/ --suri //Alice -y
+```
+
+This is particularly useful for scripting and automation.
+
+#### Quick URL Entry
+
+When prompted for a chain, you can select "Custom" to quickly type the chain URL manually, accelerating the process when
+you already know the endpoint.
+
+### Interactive Features
+
+When using the interactive mode, you'll experience:
+
+- **Predefined Actions**: Quick access to common operations like creating assets, transferring balances, etc.
+- **Filtered Selection**: Type to filter through pallets and functions for faster navigation
+- **Visual Indicators**: Clear labels showing whether an item is an `[EXTRINSIC]`, `[STORAGE]`, or `[CONSTANT]`
+- **Documentation**: Inline documentation for each pallet and function
+- **Repeat Calls**: After completing an operation, you'll be asked if you want to perform another call (unless
+  `--skip-confirm` is used)
+
+### Examples
+
+#### Example 1: Query Current Block Number
+
+```shell
+pop call chain --pallet System --function Number --url ws://localhost:9944/
+```
+
+#### Example 2: Check an Account Balance
+
+```shell
+pop call chain --pallet System --function Account --args "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY" --url ws://localhost:9944/
+```
+
+#### Example 3: Read Runtime Version
+
+```shell
+pop call chain --pallet System --function Version --url ws://localhost:9944/
+```
+
+#### Example 4: Transfer with Wallet
+
+```shell
+pop call chain --pallet Balances --function transfer_keep_alive --args "5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty" "1000000000000" --url wss://rpc.polkadot.io --use-wallet
+```
+
+#### Example 5: Sudo Call with Auto-confirm
+
+```shell
+pop call chain --pallet System --function set_code --args "./runtime.wasm" --url ws://localhost:9944/ --suri //Alice --sudo -y
+```
+
 **Need help?**
 
 Ask on [Polkadot Stack Exchange](https://polkadot.stackexchange.com/) (tag it [`pop`](https://substrate.stackexchange.com/tags/pop/info)) or drop by [our Telegram](https://t.me/onpopio). We're here to help!