diff --git a/build.sh b/build.sh
index 02290ba..bf0cbac 100755
--- a/build.sh
+++ b/build.sh
@@ -7,17 +7,17 @@ wget https://raw.githubusercontent.com/zdave-parity/jam-np/refs/heads/main/simpl
wget https://hackmd.io/@polkadot/jip1/download -O node_modules/host-call-log.md
wget https://hackmd.io/@polkadot/jip2/download -O node_modules/jip2-gav.md
-cp docs/knowledge/advanced/simple-networking/spec.md.tmpl docs/knowledge/advanced/simple-networking/spec.md
-cat node_modules/simple.md >> docs/knowledge/advanced/simple-networking/spec.md
-perl -pi -e "s/BUILD_DATE/$(date +%Y-%m-%d)/" docs/knowledge/advanced/simple-networking/spec.md
+cp docs/knowledge/simple-networking/spec.md.tmpl docs/knowledge/simple-networking/spec.md
+cat node_modules/simple.md >> docs/knowledge/simple-networking/spec.md
+perl -pi -e "s/BUILD_DATE/$(date +%Y-%m-%d)/" docs/knowledge/simple-networking/spec.md
cp docs/knowledge/testing/pvm/host-call-log.md.tmpl docs/knowledge/testing/pvm/host-call-log.md
cat node_modules/host-call-log.md >> docs/knowledge/testing/pvm/host-call-log.md
perl -pi -e "s/BUILD_DATE/$(date +%Y-%m-%d)/" docs/knowledge/testing/pvm/host-call-log.md
-cp docs/knowledge/advanced/rpc/jip2-gav.md.tmpl docs/knowledge/advanced/rpc/jip2-gav.md
-cat node_modules/jip2-gav.md >> docs/knowledge/advanced/rpc/jip2-gav.md
-perl -pi -e "s/BUILD_DATE/$(date +%Y-%m-%d)/" docs/knowledge/advanced/rpc/jip2-gav.md
+cp docs/knowledge/rpc/jip2-gav.md.tmpl docs/knowledge/rpc/jip2-gav.md
+cat node_modules/jip2-gav.md >> docs/knowledge/rpc/jip2-gav.md
+perl -pi -e "s/BUILD_DATE/$(date +%Y-%m-%d)/" docs/knowledge/rpc/jip2-gav.md
npm run convert-yaml docs/dao/index.md
diff --git a/docs/knowledge/advanced/_category_.json b/docs/knowledge/advanced/_category_.json
deleted file mode 100644
index 228150e..0000000
--- a/docs/knowledge/advanced/_category_.json
+++ /dev/null
@@ -1,9 +0,0 @@
-{
- "label": "Advanced",
- "position": 3,
- "link": {
- "type": "generated-index",
- "description": "Advanced concepts."
- }
- }
-
\ No newline at end of file
diff --git a/docs/knowledge/advanced/simple-networking/index.md b/docs/knowledge/advanced/simple-networking/index.md
deleted file mode 100644
index c7e7dfa..0000000
--- a/docs/knowledge/advanced/simple-networking/index.md
+++ /dev/null
@@ -1,6 +0,0 @@
----
-title: Networking
-sidebar_position: 1
----
-
-The JAM networking spec defines a the [Simple Networking Protocol](./spec.md) for testing. This version of the protocol will most likely not be formalized in the Graypaper. The Graypaper will only define the full version of the networking protocol once it is finalized.
diff --git a/docs/knowledge/basics/_category_.json b/docs/knowledge/basics/_category_.json
deleted file mode 100644
index 162072e..0000000
--- a/docs/knowledge/basics/_category_.json
+++ /dev/null
@@ -1,8 +0,0 @@
-{
- "label": "Basics",
- "position": 1,
- "link": {
- "type": "generated-index",
- "description": "Basics Concepts"
- }
-}
diff --git a/docs/knowledge/basics/cli-args.md b/docs/knowledge/basics/cli-args.md
deleted file mode 100644
index 55509f6..0000000
--- a/docs/knowledge/basics/cli-args.md
+++ /dev/null
@@ -1,56 +0,0 @@
----
-id: CLI Arguments
-sidebar_label: CLI Arguments
-sidebar_position: 3
-slug: /basics/cli-args
----
-
-These command line arguments should be understood by all JAM nodes to make testnet setup easy. If implementors want to deviate from their meaning or syntax, they should provide either a compatibility wrapper binary or a `testnet` subcommand on which these arguments work.
-
-## Arguments
-
-### `--bandersnatch hex`
-
-Bandersnatch Seed (only for development).
-
-### `--bls hex`
-
-BLS Seed (only for development).
-
-### `--datadir path`
-
-Specifies the directory for the blockchain, keystore, and other data.
-
-### `--ed25519 hex`
-
-Ed25519 Seed (only for development).
-
-### `--genesis path`
-
-Specifies the genesis state json file.
-
-### `--metadata string`
-
-Node metadata (default "Alice").
-
-### `--port int`
-
-Specifies the network listening port (default 9900).
-
-### `--ts int`
-
-Epoch0 Unix timestamp (will override genesis config).
-
-### `--validatorindex int`
-
-Validator Index (only for development).
-
-## Value Types
-
-### `hex`
-
-Mixed-case hex string with possible `0x` prefix.
-
-### `path`
-
-Relative or absolute file path according to the OS of being run on.
diff --git a/docs/knowledge/basics/chain-spec/index.md b/docs/knowledge/chain-spec/index.md
similarity index 98%
rename from docs/knowledge/basics/chain-spec/index.md
rename to docs/knowledge/chain-spec/index.md
index 78b3a40..35ee4a5 100644
--- a/docs/knowledge/basics/chain-spec/index.md
+++ b/docs/knowledge/chain-spec/index.md
@@ -1,7 +1,7 @@
---
sidebar_label: Chain Spec
-sidebar_position: 0
slug: /basics/chain-spec
+sidebar_position: 3
---
# Chain Spec
diff --git a/docs/knowledge/basics/chain-spec/tiny.md b/docs/knowledge/chain-spec/tiny.md
similarity index 100%
rename from docs/knowledge/basics/chain-spec/tiny.md
rename to docs/knowledge/chain-spec/tiny.md
diff --git a/docs/knowledge/basics/chain-spec/toaster.md b/docs/knowledge/chain-spec/toaster.md
similarity index 100%
rename from docs/knowledge/basics/chain-spec/toaster.md
rename to docs/knowledge/chain-spec/toaster.md
diff --git a/docs/knowledge/basics/dev-accounts.md b/docs/knowledge/dev-accounts.md
similarity index 100%
rename from docs/knowledge/basics/dev-accounts.md
rename to docs/knowledge/dev-accounts.md
diff --git a/docs/knowledge/basics/genesis-config.md b/docs/knowledge/genesis-config.md
similarity index 100%
rename from docs/knowledge/basics/genesis-config.md
rename to docs/knowledge/genesis-config.md
diff --git a/docs/knowledge/index.md b/docs/knowledge/index.md
new file mode 100644
index 0000000..247e992
--- /dev/null
+++ b/docs/knowledge/index.md
@@ -0,0 +1,20 @@
+---
+title: Welcome
+sidebar_position: 0
+slug: /
+---
+
+There are currently [over 40 teams](https://jamcha.in/clients) registered to implement JAM and [over 17](https://github.com/davxy/jam-conformance/issues) actively participating in conformance testing. Joins us to build JAM together!
+
+*This is an unofficial community-driven website. See [graypaper.com](https://graypaper.com) for official information.*
+
+### Matrix Channels
+- **[JAM Channel](https://matrix.to/#/#jam:polkadot.io)** - Technical discussions about implementing the Gray Paper
+ [archive](https://paritytech.github.io/matrix-archiver/archive/_21wBOJlzaOULZOALhaRh_3Apolkadot.io/index.html)
+- **[Gray Paper](https://matrix.to/#/#graypaper:polkadot.io)** - Discussion about the Gray Paper specification
+ [archive](https://paritytech.github.io/matrix-archiver/archive/_21ddsEwXlCWnreEGuqXZ_3Apolkadot.io/index.html)
+- **[Conformance Testing](https://matrix.to/#/#jam-conformance:matrix.org)** - Discussions about conformance testing standards
+ [archive](https://paritytech.github.io/matrix-archiver/archive/_21ksYpYHcVftKsUAsdMa_3Amatrix.org/index.html)
+
+### Discord
+- **[JAM DAO - Implementors Channel](https://discord.gg/e8UNJEPmzc)** - Casual discussions and coordination for testnet setup leading to the JAM Toaster.
diff --git a/docs/knowledge/intro.md b/docs/knowledge/intro.md
deleted file mode 100644
index 571d10f..0000000
--- a/docs/knowledge/intro.md
+++ /dev/null
@@ -1,17 +0,0 @@
----
-title: Welcome
-sidebar_position: 0
-slug: /
----
-
-:::note
-See [graypaper.com](https://graypaper.com) for official information about JAM. This is an unofficial community-driven website.
-:::
-
-Join us to build [JAM](https://graypaper.com/):
-- [JAM DAO Discord - implementors channel](https://discord.gg/e8UNJEPmzc): Casual and public channel to orchestrate a testnet setup on the way to the JAM Toaster.
-- [Matrix Gray Paper](https://matrix.to/#/#graypaper:polkadot.io) ([archive](https://paritytech.github.io/matrix-archiver/archive/_21ddsEwXlCWnreEGuqXZ_3Apolkadot.io/index.html)): Technical discussion about the Gray Paper - not implementations.
-- [Matrix JAM](https://matrix.to/#/#jam:polkadot.io) ([archive](https://paritytech.github.io/matrix-archiver/archive/_21wBOJlzaOULZOALhaRh_3Apolkadot.io/index.html)): Discussions about implementing the Gray Paper.
-- [Matrix JAM Implementers Room](https://docs.google.com/spreadsheets/d/1_Ar0CWH8cDq_mAoVkqZ20fXjfNQQ9ziv1jsVJBAfd1c/edit?gid=0#gid=0): Implementors only chat, ask a [JAM Implementer DAO member](/dao) to invite
-
-The [official](https://jam.web3.foundation/) and [unofficial](https://hackmd.io/@polkadot/jamprize) communication rules apply to all channels, have fun!
diff --git a/docs/knowledge/basics/pvm/index.md b/docs/knowledge/pvm/index.md
similarity index 99%
rename from docs/knowledge/basics/pvm/index.md
rename to docs/knowledge/pvm/index.md
index 35fb6d0..53f389a 100644
--- a/docs/knowledge/basics/pvm/index.md
+++ b/docs/knowledge/pvm/index.md
@@ -1,8 +1,8 @@
---
id: Polkadot Virtual Machine
sidebar_label: Virtual Machine
-sidebar_position: 4
slug: /basics/pvm
+sidebar_position: 5
---
The Polkadot Virtual Machine (aka *PVM*) is a Virtual Machine specification based on the RISC-V instruction set. It is based on a prototype known as PolkaVM and developed by [Parity](https://github.com/paritytech/polkavm?tab=readme-ov-file#polkavm) as an open source project. It will be utilized by the JAM Chain to provide [deterministic](#determinism) and [metered](#metering) execution and is specified in the [Gray Paper](https://graypaper.fluffylabs.dev/#/cc517d7/231100231200?v=0.6.5). It can be programmed in any language that compiles to RISC-V. Some examples are: Rust, YUL (Solidity) or C/C++.
diff --git a/docs/knowledge/advanced/rpc/index.md b/docs/knowledge/rpc/index.md
similarity index 76%
rename from docs/knowledge/advanced/rpc/index.md
rename to docs/knowledge/rpc/index.md
index a52f0b5..4781389 100644
--- a/docs/knowledge/advanced/rpc/index.md
+++ b/docs/knowledge/rpc/index.md
@@ -2,6 +2,5 @@
id: rpc
title: RPC
sidebar_label: RPC
-sidebar_position: 2
slug: /advanced/rpc
---
diff --git a/docs/knowledge/advanced/rpc/jam-duna-prop.md b/docs/knowledge/rpc/jam-duna-prop.md
similarity index 100%
rename from docs/knowledge/advanced/rpc/jam-duna-prop.md
rename to docs/knowledge/rpc/jam-duna-prop.md
diff --git a/docs/knowledge/advanced/rpc/jip2-gav.md b/docs/knowledge/rpc/jip2-gav.md
similarity index 100%
rename from docs/knowledge/advanced/rpc/jip2-gav.md
rename to docs/knowledge/rpc/jip2-gav.md
diff --git a/docs/knowledge/advanced/rpc/jip2-gav.md.tmpl b/docs/knowledge/rpc/jip2-gav.md.tmpl
similarity index 100%
rename from docs/knowledge/advanced/rpc/jip2-gav.md.tmpl
rename to docs/knowledge/rpc/jip2-gav.md.tmpl
diff --git a/docs/knowledge/advanced/simple-networking/certs.md b/docs/knowledge/simple-networking/certs.md
similarity index 94%
rename from docs/knowledge/advanced/simple-networking/certs.md
rename to docs/knowledge/simple-networking/certs.md
index 58fe8a9..0887b34 100644
--- a/docs/knowledge/advanced/simple-networking/certs.md
+++ b/docs/knowledge/simple-networking/certs.md
@@ -2,11 +2,12 @@
id: Certificates
sidebar_label: Certificates
sidebar_position: 2
+slug: /knowledge/advanced/simple-networking/certs
---
# OpenSSL Certificate Generation
-This guide demonstrates how to generate Ed25519 keys and certificates for the [Alice](/basics/dev-accounts#alice) dev account using the OpenSSL CLI. These certificates can be used for the [Simple Networking Protocol](/knowledge/advanced/simple-networking/spec.md#encryption-and-handshake).
+This guide demonstrates how to generate Ed25519 keys and certificates for the [Alice](/basics/dev-accounts#alice) dev account using the OpenSSL CLI. These certificates can be used for the [Simple Networking Protocol](/knowledge/advanced/simple-networking/spec#encryption-and-handshake).
## Secret Key Generation
@@ -61,7 +62,7 @@ openssl req -new -x509 -days 365 \
-addext "subjectAltName=DNS:$DNS_ALT_NAME"
```
-Where `$DNS_ALT_NAME` should match the [SNP Specification](/knowledge/advanced/simple-networking/spec.md#encryption-and-handshake). (The DNS alt name was reported to be wrong, please do not rely on it).
+Where `$DNS_ALT_NAME` should match the [SNP Specification](/knowledge/advanced/simple-networking/spec#encryption-and-handshake). (The DNS alt name was reported to be wrong, please do not rely on it).
For CA certificates that will sign other certificates, add these extensions:
@@ -78,7 +79,7 @@ openssl x509 -noout -text -in cert.pem
This shows:
1. The Alice public key, starting with `3b:6a:27`.
-3. The correct DNS alternative name, starting with `ehnvc`.
+2. The correct DNS alternative name, starting with `ehnvc`.
Example output for Alice's certificate:
```pre
diff --git a/docs/knowledge/advanced/simple-networking/conn_grid.md b/docs/knowledge/simple-networking/conn_grid.md
similarity index 97%
rename from docs/knowledge/advanced/simple-networking/conn_grid.md
rename to docs/knowledge/simple-networking/conn_grid.md
index af70aa7..989cb85 100644
--- a/docs/knowledge/advanced/simple-networking/conn_grid.md
+++ b/docs/knowledge/simple-networking/conn_grid.md
@@ -2,6 +2,7 @@
id: Block Propagation Grid
sidebar_label: Block Propagation Grid
sidebar_position: 3
+slug: /knowledge/advanced/simple-networking/Block Propagation Grid
---
The SNP spec specifies that nodes need to announce their blocks only to specific peers - not to the whole network. Our interpretation of the SNP spec leads to the following grid for block propagation:
diff --git a/docs/knowledge/simple-networking/index.md b/docs/knowledge/simple-networking/index.md
new file mode 100644
index 0000000..3a64f0c
--- /dev/null
+++ b/docs/knowledge/simple-networking/index.md
@@ -0,0 +1,7 @@
+---
+title: P2P Networking
+slug: /knowledge/advanced/simple-networking
+sidebar_position: 6
+---
+
+The JAM networking spec defines a the [Simple Networking Protocol](/knowledge/advanced/simple-networking/spec) for testing. This version of the protocol will most likely not be formalized in the Graypaper. The Graypaper will only define the full version of the networking protocol once it is finalized.
diff --git a/docs/knowledge/advanced/simple-networking/spec.md b/docs/knowledge/simple-networking/spec.md
similarity index 99%
rename from docs/knowledge/advanced/simple-networking/spec.md
rename to docs/knowledge/simple-networking/spec.md
index 0beb1e9..c915ebc 100644
--- a/docs/knowledge/advanced/simple-networking/spec.md
+++ b/docs/knowledge/simple-networking/spec.md
@@ -2,6 +2,7 @@
id: spec
sidebar_label: Spec
sidebar_position: 1
+slug: /knowledge/advanced/simple-networking/spec
---
(source https://github.com/zdave-parity/jam-np/blob/main/simple.md from 2025-09-19)
diff --git a/docs/knowledge/advanced/simple-networking/spec.md.tmpl b/docs/knowledge/simple-networking/spec.md.tmpl
similarity index 80%
rename from docs/knowledge/advanced/simple-networking/spec.md.tmpl
rename to docs/knowledge/simple-networking/spec.md.tmpl
index 6927d6c..a06c4c7 100644
--- a/docs/knowledge/advanced/simple-networking/spec.md.tmpl
+++ b/docs/knowledge/simple-networking/spec.md.tmpl
@@ -2,6 +2,7 @@
id: spec
sidebar_label: Spec
sidebar_position: 1
+slug: /knowledge/advanced/simple-networking/spec
---
(source https://github.com/zdave-parity/jam-np/blob/main/simple.md from BUILD_DATE)
diff --git a/docs/knowledge/advanced/state/index.mdx b/docs/knowledge/state/index.mdx
similarity index 88%
rename from docs/knowledge/advanced/state/index.mdx
rename to docs/knowledge/state/index.mdx
index 62f9ea1..4c6e45c 100644
--- a/docs/knowledge/advanced/state/index.mdx
+++ b/docs/knowledge/state/index.mdx
@@ -1,13 +1,9 @@
---
title: State Keys
-sidebar_position: 3
slug: /advanced/storage/keys
+sidebar_position: 4
---
-:::warning
-🚧 This is work in progress and may contain errors.
-:::
-
# State Key Search
State keys in JAM are 31 bytes long and generated by the [state-key constructor function $C$](https://graypaper.fluffylabs.dev/#/7e6ff6a/3b11003b1100?v=0.6.7). $C$ is generally not invertible; it is therefore impossible to always reconstruct the input to $C$ from the key.
diff --git a/docs/knowledge/advanced/telemetry/index.md b/docs/knowledge/telemetry/index.md
similarity index 94%
rename from docs/knowledge/advanced/telemetry/index.md
rename to docs/knowledge/telemetry/index.md
index 36ee33f..b4edff5 100644
--- a/docs/knowledge/advanced/telemetry/index.md
+++ b/docs/knowledge/telemetry/index.md
@@ -1,6 +1,6 @@
---
title: Telemetry
-sidebar_position: 3
+slug: /knowledge/advanced/telemetry
---
We outline a protospec for using
@@ -22,7 +22,7 @@ how to deal with errors and precise formats with a few teams.
### JAMNP + OpenTelemetry
-The [JAMNP spec](/knowledge/advanced/simple-networking/spec.md) is used as a primary starting point to develop a telemetry system:
+The [JAMNP spec](/knowledge/advanced/simple-networking/spec) is used as a primary starting point to develop a telemetry system:
1. UP 0: Block Announcement
2. CE 128: Block Request
diff --git a/docs/knowledge/testing/_category_.json b/docs/knowledge/testing/_category_.json
index 7087b50..2cf3139 100644
--- a/docs/knowledge/testing/_category_.json
+++ b/docs/knowledge/testing/_category_.json
@@ -1,6 +1,5 @@
{
"label": "Testing",
- "position": 2,
"link": {
"type": "generated-index",
"description": "All important testing tools, both official and unofficial."
diff --git a/justfile b/justfile
index 9e2c3eb..fce429b 100644
--- a/justfile
+++ b/justfile
@@ -1,7 +1,7 @@
default: dev
dev:
- yarn start
+ yarn start --no-open
build:
sh build.sh