docs: improve documentation and add Claude Code guidance

- Add CLAUDE.md with repository guidance for Claude Code assistant
- Standardize shell code blocks to use 'sh' instead of 'bash'
- Add spell checker words to VS Code settings
- Simplify README project description for clarity
- Add temporary files pattern to .gitignore

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: steinerkelvin

.gitignore

@@ -1,3 +1,6 @@
+# Local files
+*.local.*
+
 # Temporary files
 /tmp/
 

.vscode/settings.json

@@ -12,10 +12,13 @@
   "coverage-gutters.coverageFileNames": ["target/cov.xml"],
   // Spell checker
   "cSpell.words": [
+    "alice",
     "buildx",
     "devcontainers",
+    "extrinsics",
     "irongut",
     "jwalton",
+    "mainnet",
     "presign",
     "Swatinem",
     "wbuild"

CLAUDE.md

@@ -0,0 +1,34 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with this Substrate blockchain repository.
+
+## References
+
+- @README.md - Project overview, quick start, network setup
+- @CONTRIBUTING.md - Development setup (Nix), guidelines, testing
+- @docs/pallet-structure.md - Architecture and API design
+- @docs/xtask-manual.md - Development tooling guide
+
+## Core Pallets
+
+- **`torus0`**: Agent registration, staking, burn mechanisms
+- **`emission0`**: Token distribution with linear emission algorithm  
+- **`governance`**: Proposals, voting, treasury, roles
+- **`permission0`**: Permission and access control
+
+## Essential Commands
+
+```sh
+nix develop          # Enter development environment
+just                 # Run checks and tests (default)
+just check           # Clippy linting only
+just test            # Test suite only
+cargo xtask coverage # Test coverage report
+```
+
+## Critical Safety Rules
+
+- Never use `unwrap()`, `expect()`, or panicking operations in pallet code
+- Use `checked_div()` instead of `/` for arithmetic operations  
+- Panics in runtime code will halt the chain
+- Use `FixedU128` for financial calculations

CONTRIBUTING.md

@@ -18,19 +18,22 @@ The project uses Nix flakes to manage dependencies and ensure a consistent devel
 
 1. Install Nix package manager by following the instructions at [nixos.org](https://nixos.org/download.html)
 2. Enable flakes by adding the following to your `~/.config/nix/nix.conf` or `/etc/nix/nix.conf`:
-   ```
+
+   ```conf
    experimental-features = nix-command flakes
    ```
+
 3. Enter the development environment:
 
-   ```bash
+   ```sh
    nix develop
    ```
 
    This will set up the correct Rust version, git, and precompiled binaries for dependencies like RocksDB and OpenSSL.
 
 4. Build the project:
-   ```bash
+
+   ```sh
    cargo build --release
    ```
 
@@ -92,23 +95,23 @@ For detailed guidance on creating migrations, refer to the [Substrate Storage Mi
 
 1. Fork the repo and create a new branch for your feature or bugfix:
 
-   ```bash
+   ```sh
    git checkout -b feature/your-feature-name
    ```
 
 2. Make your changes, following our code guidelines and testing requirements
 
 3. Run tests and checks to ensure your changes don't break existing functionality:
 
-   ```bash
+   ```sh
    cargo fmt
    cargo clippy
    cargo test
    ```
 
 4. Check code coverage to ensure sufficient test coverage:
 
-   ```bash
+   ```sh
    cargo xtask coverage
    ```
 
@@ -125,7 +128,7 @@ Strong test coverage is a core value for our project. All pallets must maintain
 
 Run the following command to generate a `Cobertura` xml file on `target/cov.xml` that can be used with the [Coverage Gutters](https://marketplace.visualstudio.com/items?itemName=ryanluker.vscode-coverage-gutters) VSCode plugin to display which functions and branches are not covered by tests yet.
 
-```bash
+```sh
 cargo xtask coverage
 ```
 

README.md

@@ -4,10 +4,9 @@
 
 ![Docker Build](https://github.com/renlabs-dev/torus-substrate/actions/workflows/build-docker.yml/badge.svg)
 
-Torus is a self-assembling and evolving peer-to-peer blockchain organism, with a
-stake-driven network built in Rust with the Substrate framework. Torus powers an
-innovative ecosystem of agents and incentives, incorporating diverse
-technologies into its collective body.
+Torus is a self-assembling and evolving peer-to-peer organism with a
+stake-driven ecosystem of agents and incentives. It's core coordination system
+is a blockchain built on Substrate, implemented in this repository.
 
 ## Table of Contents
 
@@ -74,7 +73,7 @@ The Torus node operates on two primary ports:
 
 We have tools to simulate a network locally as well. The `cargo xtask run` command allows you to run a local network from scratch by setting up nodes with fresh spec files:
 
-```bash
+```sh
 cargo xtask generate-spec gen-new --sudo <your Torus key> -o myspec.json
 cargo xtask run local --chain myspec.json --alice --node-validator true &
 cargo xtask run local --chain myspec.json --bob --node-validator true &
@@ -84,21 +83,21 @@ The `generate-spec` command has been expanded with subcommands that allow you to
 
 1. Generate a new empty chain spec with custom parameters:
 
-```bash
+```sh
 cargo xtask generate-spec gen-new --name "My Custom Chain" --sudo <your Torus key> -o myspec.json
 ```
 
 2. Generate a replica of the mainnet:
 
-```bash
+```sh
 cargo xtask generate-spec gen-replica --sudo <your Torus key> -o myreplica.json
 ```
 
 You can also pass an `--api-url` flag with a WS endpoint to clone the state from.
 
 Both commands take additional parameters to configure Aura, Grandpa and balances. For example:
 
-```bash
+```sh
 cargo xtask generate-spec gen-new \
   --name "My Chain" \
   --sudo <your Torus key> \
@@ -110,7 +109,7 @@ cargo xtask generate-spec gen-new \
 
 You can then run nodes with the generated specs:
 
-```bash
+```sh
 cargo xtask run local --chain myspec.json --alice --node-validator true &
 cargo xtask run local --chain myspec.json --bob --node-validator true &
 ```

docs/xtask-manual.md

@@ -20,7 +20,7 @@ The `run` command launches Torus nodes with various configuration options. It of
 
 The local mode starts a node using either a provided chain spec file or the default development configuration:
 
-```bash
+```sh
 cargo xtask run local [OPTIONS]
 ```
 
@@ -38,7 +38,7 @@ The Alice and Bob accounts come with predefined keys and network configurations.
 
 The replica mode creates and runs a node that replicates the mainnet state:
 
-```bash
+```sh
 cargo xtask run replica [OPTIONS]
 ```
 
@@ -58,7 +58,7 @@ The `generate-spec` command creates chain specification files that define the in
 
 The `gen-new` subcommand creates a fresh chain specification with customizable parameters:
 
-```bash
+```sh
 cargo xtask generate-spec gen-new [OPTIONS] -o <OUTPUT_FILE>
 ```
 
@@ -73,7 +73,7 @@ Important options include:
 
 For example, to create a new chain with custom authorities and initial balances:
 
-```bash
+```sh
 cargo xtask generate-spec gen-new \
   --name "My Test Network" \
   --sudo 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY \
@@ -87,7 +87,7 @@ cargo xtask generate-spec gen-new \
 
 The `gen-replica` subcommand creates a chain specification that replicates the current mainnet state:
 
-```bash
+```sh
 cargo xtask generate-spec gen-replica [OPTIONS] -o <OUTPUT_FILE>
 ```
 
@@ -100,7 +100,7 @@ This command fetches the entire state from a running node and creates a chain sp
 
 Example usage:
 
-```bash
+```sh
 cargo xtask generate-spec gen-replica \
   --sudo 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY \
   --api-url "wss://my-custom-node.torus.network" \
@@ -125,7 +125,7 @@ The typical workflow is to first generate a chain spec file with desired propert
 
 Here's an example of setting up a two-node local network:
 
-```bash
+```sh
 # Generate a chain spec
 cargo xtask generate-spec gen-new --sudo 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY -o local-spec.json
 
@@ -142,7 +142,7 @@ The nodes will automatically connect to each other and start producing blocks si
 
 The `coverage` command generates code coverage reports for the Torus pallets:
 
-```bash
+```sh
 cargo xtask coverage [--html]
 ```
 
@@ -158,7 +158,7 @@ The xtask tools use several techniques to simplify working with Torus. It provid
 
 You can customize various node parameters to fit your specific needs:
 
-```bash
+```sh
 cargo xtask run local [OPTIONS] --chain-spec my-spec.json \
   --node-name "Custom Node" \
   --node-key <KEY> \
@@ -168,13 +168,13 @@ cargo xtask run local [OPTIONS] --chain-spec my-spec.json \
 
 For testing in isolation, you can prevent the node from connecting to other peers with the `--isolated` flag:
 
-```bash
+```sh
 cargo xtask run local --chain-spec my-spec.json --isolated
 ```
 
 You can also specify custom bootnodes for your node to connect to:
 
-```bash
+```sh
 cargo xtask run local --chain-spec my-spec.json \
   --bootnodes "/ip4/192.168.1.1/tcp/30333/p2p/<node-id>" \
   --bootnodes "/ip4/192.168.1.2/tcp/30333/p2p/<node-id>"
@@ -186,6 +186,6 @@ When working with xtask, you might encounter some common issues. If a node fails
 
 For debugging purposes, you can examine the temporary node directories to check logs and configuration files. The path is printed when the node starts. You can also run a node without using xtask to get more detailed logs:
 
-```bash
+```sh
 ./target/release/torus-node -d /tmp/node-data --chain my-spec.json --validator
 ```