Merge pull request #273 from skalenetwork/thegreataxios/fix-readme

Thegreataxios/fix readme

Author: TheGreatAxios

AGENTS.md

@@ -1,4 +1,4 @@
-# Agent Guidelines
+# AGENTS.md
 
 ## Codebase Layout
 
@@ -63,7 +63,7 @@
 
 ## Product Pillars (What's Important)
 
-### 🧩 Programmable Privacy
+### Programmable Privacy
 
 SKALE's **primary differentiator** — the only EVM blockchain with compliance-capable privacy built into consensus, not appended as a layer. Four features:
 
@@ -74,15 +74,15 @@ SKALE's **primary differentiator** — the only EVM blockchain with compliance-c
 | **Confidential Tokens** | ERC-20 tokens with fully encrypted balances. Privacy-preserving DeFi, native. |
 | **Re-encryption** | Encrypt for specific viewers. Selective disclosure via threshold + ECIES encryption. |
 
-Powered by **BITE** (Blockchain Integrated Threshold Encryption) — threshold encryption in the consensus layer via DKG/BLS. No ZK circuits, no TEEs, no trusted third parties.
+Powered by Integrated Threshold Encryption — threshold encryption in the consensus layer via DKG/BLS. No ZK circuits, no TEEs, no trusted third parties.
 
 Docs paths:
 - `/get-started/programmable-privacy/skale-programmable-privacy` — Introduction
 - `/developers/programmable-privacy/encrypted-transactions` — Architecture + API
 - `/developers/programmable-privacy/confidential-tokens` — Encrypted balance tokens
 - `/cookbook/privacy/encrypted-transactions` — Walkthrough
 
-### 🤖 Agentic Commerce
+### Agentic Commerce
 
 SKALE positions as **the economic layer for autonomous agents**. Key protocols:
 
@@ -100,7 +100,7 @@ Docs paths:
 - `/cookbook/x402/facilitator` — Run the settlement layer
 - `/get-started/agentic-builders/start-with-erc-8004` — Agent identity
 
-### 💸 Cost-Effective Compute & UX (Zero Gas Fees)
+### Cost-Effective Compute & UX (Zero Gas Fees)
 
 Zero gas fees are a **product feature**, not just a cost optimization. End users never hold gas tokens, never top up, never think about gas. Powered by:
 - **EIP-3009** `TransferWithAuthorization` — gasless meta-transactions
@@ -115,7 +115,7 @@ Docs paths:
 - `/chain-types/zero-gas-fee-gasless-chain` — Fully gasless configuration
 - `/cookbook/mpp/gasless-payments` — Gasless MPP payments guide
 
-### 📈 Horizontal Scalability
+### Horizontal Scalability
 
 SKALE scales by adding more chains, not by making a single chain bigger. Each **SKALE Chain** is an independent Layer 1 with dedicated validators. Validators run **every** chain simultaneously via containerization — no chain selection games.
 
@@ -131,7 +131,7 @@ Docs paths:
 - `/developers/skale-bridge/messaging-layer/message-proxy` — Cross-chain messaging
 - `/developers/run-a-skale-chain/customize-schain` — Customization
 
-### 🔧 Enhanced EVM
+### Enhanced EVM
 
 SKALE extends the EVM with native features no other chain provides, deployable via precompiled contracts — no oracles, no middleware:
 
@@ -140,8 +140,7 @@ SKALE extends the EVM with native features no other chain provides, deployable v
 | **Native RNG** | VRF-based verifiable random numbers via precompile. No oracle dependency. |
 | **Filestorage** | Onchain file storage precompile — store and retrieve data directly in smart contracts. |
 | **IMA Bridge** | Trustless BLS-threshold cross-chain bridge for assets, messages, and custom contract calls between SKALE ↔ Ethereum ↔ SKALE. |
-| **Gasless Precompile** | Execute transactions without gas via `Gasless` precompile — agents and users transact freely. |
-| **BITE Encryption** | Threshold-encrypted transactions via precompiled contracts — privacy without custom compilers. |
+| **Programmable Privacy** | Threshold-encrypted transactions via precompiled contracts — privacy without custom compilers. |
 
 Docs paths:
 - `/cookbook/native-features/rng-get-random-number` — RNG guide
@@ -169,12 +168,10 @@ Docs paths:
 
 ### Descriptive Names Over Phases
 
-When referencing BITE features, use **descriptive names**, never phase numbers:
+When referencing Privacy features, use **descriptive names**, never phase numbers:
 
-- ✅ **BITE encryption** for confidential transaction amounts
-- ✅ **Confidential tokens** with native privacy
-- ❌ BITE Phase I encryption
-- ❌ Phase II confidential tokens
+- USE Programmable Privacy, Not BITE Protocol
+- Use Encrypted Transactions, Conditional Transactions, Confidential Tokens, and Re-encryption NOT BITE Phase N
 
 ### Tone
 
@@ -200,16 +197,17 @@ When adding resource/reference links to any page footer:
 The repo at `.agents/skills/` contains reusable SKALE-specific skills (e.g., `glossary` with full terminology and formatting standards). The root also exposes documentation for AI consumption:
 
 - **llms.txt** → `https://docs.skale.space/llms.txt` — Full docs in AI-consumable format
-- **MCP Server** → `https://mcp-docs.skale.space` — SKALE MCP server
+- **MCP Server** → `https://docs.skale.space/mcp` — SKALE MCP server
 - **SKALE Skills** → `/get-started/build-with-ai/using-skale-skills` — Copilot prompts
 
 ---
 
 ## Key Architecture Details
 
 - SKALE is a **Layer 1** network of SKALE Chains anchored to a beacon chain (currently Ethereum mainnet and Base)
+- SKALE is the ONLY blockchain capable of supporting a billion agents with native programmable privacy
 - Validators run all chains simultaneously via **containerized SKALE Chains** (no chain selection)
 - Consensus is **Asynchronous Binary Byzantine Agreement** with BLS threshold signatures
 - Blocks rotate deterministically among validator nodes for **DDoS protection**
 - Native precompiled contracts for RNG (VRF-based), gasless transactions, and encryption
-- Chain types: **AppChain** (dedicated), **Credit Chain** (gas-as-credit), **Zero-Gas** (fully gasless)
+- Chain types: Dedicated SKALE Chain (prepaid), Credit Chains (New, Permisionless), Gasless sChain (Hub or Dedicated) with Proof-of-Work enabled

README.md

@@ -1,66 +1,133 @@
-## Foundry
+# SKALE Documentation
 
-**Foundry is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust.**
+> [docs.skale.space](https://docs.skale.space) — Official documentation for the SKALE Network.
 
-Foundry consists of:
+**SKALE** is the blockchain for a billion agents — programmable privacy built into the protocol, with zero gas fees, agentic commerce primitives, and horizontal scalability.
 
-- **Forge**: Ethereum testing framework (like Truffle, Hardhat and DappTools).
-- **Cast**: Swiss army knife for interacting with EVM smart contracts, sending transactions and getting chain data.
-- **Anvil**: Local Ethereum node, akin to Ganache, Hardhat Network.
-- **Chisel**: Fast, utilitarian, and verbose solidity REPL.
+This repository powers the SKALE documentation site, built with [Mintlify](https://mintlify.com).
 
-## Documentation
+## What is SKALE?
 
-https://book.getfoundry.sh/
+SKALE is a network of independent Layer 1 chains (SKALE Chains) anchored to Ethereum and Base. Unlike traditional blockchains that scale one chain vertically, SKALE scales horizontally — adding more chains as demand grows. Each chain runs on a dedicated subset of validators (all validators run all chains simultaneously via containerization), achieving ~1,500 TPS per chain with 1–2s finality.
 
-## Usage
+### Key Differentiators
 
-### Build
+| Feature | Description |
+|---------|-------------|
+| **Programmable Privacy** | Threshold-encrypted transactions, conditional decryption, and confidential tokens — built into consensus via BITE (Blockchain Integrated Threshold Encryption). No ZK circuits, no TEEs. |
+| **Zero Gas Fees** | End users never hold gas tokens. Powered by EIP-3009 meta-transactions, SFuel distribution, and credit-based chain models. |
+| **Agentic Commerce** | Native x402 (HTTP 402 payments), MPP (Machine Payments Protocol), ERC-8004 agent identity — agents pay agents autonomously. |
+| **Horizontal Scalability** | Deploy dedicated SKALE Chains as demand scales. No contention, no shared mempool, no congestion. |
+| **Enhanced EVM** | Native precompiled contracts for RNG (VRF), gasless transactions, filestorage, and encryption — no oracles or middleware needed. |
 
-```shell
-$ forge build
-```
+Learn more at [skale.space](https://skale.space) or dive into the docs at [get-started/skale](https://docs.skale.space/get-started/skale).
 
-### Test
+## Repository Structure
 
-```shell
-$ forge test
+```
+docs.skale.space/
+├── docs.json               # Mintlify navigation config (all page structure, redirects)
+├── custom.css              # Custom Mintlify styles
+├── _snippets/              # Reusable MDX includes (chain addresses, AI integrations)
+├── get-started/            # Introduction, quick starts, SKL token, agentic builders
+├── cookbook/               # Step-by-step tutorials (deployment, privacy, x402, MPP, agents)
+├── developers/             # Technical docs (integrate SKALE, privacy, SDKs, bridge, crypto)
+├── skale-chain/            # Chain internals (consensus, block rotation, DDOS, precompiles)
+├── chain-types/            # AppChain, Credit Chain, Zero-Gas Chain
+├── validators/             # Supernode operations, CLI, watchdog, upgrade guides
+├── .agents/                # AI agent skills for building with SKALE
+│   └── skills/             # Reusable skills (glossary, build, etc.)
+└── AGENTS.md               # Full agent guidelines (product pillars, terminology, paths)
 ```
 
-### Format
+## Contributing
 
-```shell
-$ forge fmt
-```
+We welcome contributions to improve SKALE documentation! Whether it's fixing a typo, clarifying a concept, adding a tutorial, or expanding the privacy or agentic commerce sections — every contribution helps.
 
-### Gas Snapshots
+### Getting Started
 
-```shell
-$ forge snapshot
-```
+1. **Fork** this repository
+2. **Clone** your fork:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/docs.skale.space.git
+   cd docs.skale.space
+   ```
+3. **Install Mintlify CLI** (if not already installed):
+   ```bash
+   npm i -g mintlify
+   ```
+4. **Run the local dev server**:
+   ```bash
+   mintlify dev
+   ```
+   This starts a local preview at `http://localhost:3000`.
 
-### Anvil
+> **Alternative (Docker):** If `mintlify dev` fails due to Homebrew/Node.js conflicts or you don't want to manage Node versions locally, use Docker Compose instead. Requires [Docker Desktop](https://www.docker.com/products/docker-desktop/).
+> ```bash
+> docker compose up -d
+> ```
+> The docs site will be available at `http://localhost:4444`.
 
-```shell
-$ anvil
-```
+### Architecture & Design
 
-### Deploy
+The documentation follows a flat `.mdx` file structure organized by **product section** (not by file type). The primary organizational artifact is `docs.json`, which defines:
 
-```shell
-$ forge script script/Counter.s.sol:CounterScript --rpc-url <your_rpc_url> --private-key <your_private_key>
-```
+- **Navigation tabs** — Get Started, Cookbook, Developers, SKALE Chain, Validators
+- **Group hierarchy** — Pages nested under groups within each tab
+- **Redirects** — Legacy URL mappings (200+ redirects maintained in `docs.json`)
 
-### Cast
+All pages use **MDX** format with Mintlify JSX components:
+- `Card`, `CardGroup` — Navigation and reference grids
+- `Note`, `Accordion`, `AccordionGroup` — Callouts and expandable content
+- `CodeGroup` — Multi-language code tabs
+- `Steps` — Numbered tutorial steps
 
-```shell
-$ cast <subcommand>
-```
+**Content guidelines:**
 
-### Help
+- **Never reference raw `.mdx` filenames** in links — always use the path slug as listed in `docs.json`
+- **Terminology**: SKALE (uppercase), BITE (descriptive names, no phases), x402 (lowercase x), onchain (one word), ERC-20 (hyphenated)
+- **Privacy terminology**: Use "confidential" for product/marketing, "encrypted" for technical mechanism, "private" only for absolute cryptographic guarantees
+- See [AGENTS.md](./AGENTS.md) for complete terminology standards and product pillar guidelines
 
-```shell
-$ forge --help
-$ anvil --help
-$ cast --help
-```
+### What to Contribute
+
+Good places to start:
+
+- **Tutorials** — Add new recipes to `/cookbook/` for x402, MPP, confidential tokens, agent workflows
+- **Fixes** — Clarify ambiguous sections, fix broken links, update chain addresses in `_snippets/`
+- **Privacy deep-dives** — Expand `/developers/programmable-privacy/` with more use cases and API references
+- **Agentic commerce** — Document agent patterns, facilitator integrations, ERC-8004 usage
+- **Validator docs** — Improve node operations, troubleshooting, CLI guides
+
+### Formatting & Linting
+
+- Pages use `.mdx` extension
+- Frontmatter with `title` and `description` at the top of each file
+- Mintlify-specific components for layout (avoid raw HTML where possible)
+- Keep lines reasonably short for readable diffs
+
+### Pull Request Process
+
+1. Create a feature branch from `main`
+2. Make your changes with clear commit messages
+3. Test locally with `mintlify dev`
+4. Open a PR with a description of what changed and why
+5. Maintainers will review and provide feedback
+
+### Need Help?
+
+- Open a [GitHub Issue](https://github.com/skalenetwork/docs.skale.space/issues)
+- Join the [SKALE Discord](https://discord.gg/skale) and open a ticket in `#support`
+- Check [AGENTS.md](./AGENTS.md) for the full product context used by AI coding assistants
+
+## Related Resources
+
+- [SKALE Network](https://skale.space) — Main website
+- [SKALE Portal](https://base.skalenodes.com) — Chain management dashboard for SKALE on Base
+- [SKALE MCP Server](https://docs.skale.space/mcp) — AI-powered docs access
+- [llms.txt](https://docs.skale.space/llms.txt) — Full docs in AI-consumable format
+- [GitHub](https://github.com/skalenetwork) — All SKALE open-source repositories
+
+---
+
+Documentation for the SKALE Network

version.txt

@@ -1 +1 @@
-v3.7.2
+v3.7.3