docs: comprehensive documentation matching official Bittensor Python SDK quality

- Complete rewrite of all documentation (39 files, 17,874 lines)
- README.md: architecture diagram, crate table, feature flags, code examples
- Getting started guide with connection, queries, transfers, wallets
- Architecture overview with data flow diagrams and extension points
- Full crate references: wallet, chain-client, synapse, axon, dendrite, metagraph
- 12 query module references (account, delegate, neuron, subnet, staking, etc.)
- 10 extrinsic module references (staking, transfer, weights, registration, etc.)
- CLI reference (btcli-rs) with all subcommands
- TUI dashboard reference
- Python bindings reference (bittensor_rs package)
- WASM bindings reference for browser usage
- Migration guide from Python SDK to Rust with before/after examples
- Glossary and FAQ
- Removed obsolete docs (chain.md, validator.md, types.md, utils.md)
- Fixed all old API paths (bittensor_rs → bittensor_chain)

Author: echobt

README.md

@@ -1,6 +1,6 @@
 # bittensor-rs
 
-Rust SDK for the Bittensor network — wallet management, chain interaction, neuron serving, and subnet monitoring.
+Rust SDK for the Bittensor decentralized AI network. Wallet management, chain interaction, neuron serving, and subnet monitoring, built on subxt 0.50 with typed storage queries and extrinsics.
 
 ## Architecture
 
@@ -69,9 +69,50 @@ Rust SDK for the Bittensor network — wallet management, chain interaction, neu
 | **bittensor-wasm** | WASM bindings for browser usage |
 | **bittensor-examples** | Runnable code samples |
 
+## Feature Flags
+
+### bittensor-chain
+
+| Feature | Default | Description |
+|---|---|---|
+| `storage-subscriptions` | yes | Enable `subscribe_storage` event stream |
+| `drand` | no | Drand randomness beacon verification |
+| `mev-shield` | no | Post-quantum MEV protection for extrinsics |
+| `integration-tests` | no | Integration test suite (requires local node) |
+
+### bittensor-metagraph
+
+| Feature | Default | Description |
+|---|---|---|
+| `ml-backend` | no | ML-based weight scoring backend |
+
+### bittensor-cli
+
+| Feature | Default | Description |
+|---|---|---|
+| `mev` | no | MEV-shield protected transactions |
+
+## Python SDK vs Rust SDK
+
+| Feature | Python SDK | Rust SDK |
+|---|---|---|
+| Performance | Interpreter overhead | Native binary, zero-cost abstractions |
+| Memory safety | GC managed | Compile-time borrow checking |
+| Concurrency | GIL-limited async | Native async with tokio, no GIL |
+| WASM support | No | Full wasm-bindgen support |
+| Python bindings | Native | Via bittensor-pyo3 (`bittensor_rs`) |
+| Typing | Runtime duck typing | Static types, subxt-generated metadata |
+| Keyfile format | NaCl secretbox | Same NaCl secretbox, cross-compatible |
+| Chain client | substrate-interface | subxt 0.50, typed storage + extrinsics |
+
 ## Getting Started
 
-Add to your `Cargo.toml`:
+### Requirements
+
+- Rust 1.85+ (Edition 2024)
+- A running Subtensor node (finney, test, or local)
+
+### Add Dependencies
 
 ```toml
 [dependencies]
@@ -80,19 +121,104 @@ bittensor-chain = "0.1"
 bittensor-wallet = "0.1"
 ```
 
-Connect and query:
+Or via cargo:
+
+```sh
+cargo add bittensor-core bittensor-chain bittensor-wallet
+```
+
+### Connect and Query
 
 ```rust,no_run
 use bittensor_chain::prelude::SubtensorClient;
 use bittensor_core::config::NetworkConfig;
 
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let client = SubtensorClient::from_config(NetworkConfig::finney()).await?;
+    let block = client.at_current_block().await?;
+    println!("Connected at block {:?}", block.block_hash());
+    Ok(())
+}
+```
+
+### Query Balance
+
+```rust,no_run
+use bittensor_chain::prelude::*;
+use bittensor_core::config::NetworkConfig;
+use bittensor_core::balance::Balance;
+
 let client = SubtensorClient::from_config(NetworkConfig::finney()).await?;
+let balance: Balance = bittensor_chain::queries::account::get_balance(
+    client.rpc(), &account_id
+).await?;
+println!("Balance: {balance}");
 ```
 
-## Requirements
+### Transfer TAO
 
-- Rust 1.85+ (Edition 2024)
-- A running Subtensor node (finney, test, or local)
+```rust,no_run
+use bittensor_chain::prelude::*;
+use bittensor_core::config::NetworkConfig;
+use bittensor_core::balance::Balance;
+
+let client = SubtensorClient::from_config(NetworkConfig::finney()).await?;
+let signer = subxt_signer::sr25519::Keypair::from_uri("//Alice")?;
+let dest = subxt_signer::sr25519::PublicKey::from_uri("//Bob")?;
+let amount = Balance::from_tao(1.0);
+
+bittensor_chain::extrinsics::transfer::transfer(
+    client.rpc(), &signer, &dest, amount.to_rao()
+).await?;
+```
+
+### Create a Wallet
+
+```rust
+use bittensor_wallet::prelude::*;
+
+let mut wallet = Wallet::new("default");
+let mnemonic = wallet.create_coldkey("my-password")?;
+println!("Back up this mnemonic: {mnemonic}");
+println!("Coldkey address: {}", wallet.get_coldkeypub()?);
+
+let hotkey = wallet.create_hotkey()?;
+println!("Hotkey address: {}", hotkey.ss58_address());
+```
+
+### Network Endpoints
+
+| Network | WebSocket URL |
+|---|---|
+| Finney (mainnet) | `wss://entrypoint-finney.opentensor.ai:443` |
+| Testnet | `wss://test.finney.opentensor.ai:443` |
+| Local | `ws://127.0.0.1:9944` |
+| Archive | `wss://archive.finney.opentensor.ai:443` |
+
+You can also connect directly with `SubtensorClient::from_url`:
+
+```rust,no_run
+let client = SubtensorClient::from_url("wss://entrypoint-finney.opentensor.ai:443").await?;
+```
+
+## Documentation
+
+Full documentation is available in the `docs/` directory:
+
+- [Documentation Index](docs/index.md)
+- [Getting Started](docs/getting-started.md)
+- [Architecture](docs/architecture.md)
+
+## Metadata
+
+Chain metadata is stored at `metadata/finney.scale` and auto-loaded at compile time. When the Finney runtime upgrades, regenerate the metadata and API bindings:
+
+```sh
+cargo install subxt-cli@0.50.0 --locked
+subxt metadata --url wss://entrypoint-finney.opentensor.ai:443 -f bytes > metadata/finney.scale
+cargo check -p bittensor-chain
+```
 
 ## License