add overview page for blockchain foundation

[fakela]

This PR closes #51

[github-actions]

Thanks for the updates to the TON docs, especially in ton/overview.mdx. A few items need fixes for links, headings, and terminology before merge.

Findings (10)

High (2)

[HIGH] Missing H1 at top of page

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/0b23f298cdfd10500377b2accf8338ba819a28e6/ton/overview.mdx?plain=1#L5-L5

Description:
After the frontmatter, the page begins with a paragraph rather than a single top-level H1 that matches the title. This breaks navigation and TOC conventions and makes anchors inconsistent. The title in frontmatter is “Overview”, so the first visible content should be a matching # Overview heading.

Suggestion:
Add an H1 immediately before the opening paragraph.

@@
-This section introduces the core concepts of the TON Blockchain. It explains the fundamental building blocks of the system, including data structures, transaction flow, consensus mechanisms, and network protocols.
+# Overview
+This section introduces the core concepts of the TON Blockchain. It explains the fundamental building blocks of the system, including data structures, transaction flow, consensus mechanisms, and network protocols.

[HIGH] Broken or incorrect internal links

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/0b23f298cdfd10500377b2accf8338ba819a28e6/ton/overview.mdx?plain=1#L13-L14

Description:
The links to “Cells” and “Addresses” point to directory paths that have no concrete index pages in the repo (ton/cells and ton/addresses have no index.mdx or *.mdx at those exact paths). Additional broken/ambiguous targets appear at L28 (“Blocks” links to /ton/, which is a section overview, not a blocks page) and L37 (“TVM Whitepaper” links to /ton/wtvm, which does not exist; ton/tvm.mdx exists). These issues likely cause 404s or land users on ambiguous pages, undermining navigation.

Suggestion:
Update targets to existing pages.

- - **[Cells](/ton/cells)** – TON’s universal data structure, used to represent every piece of information on-chain, from account states to transactions, in a compact and hash-friendly format.  
+ - **[Cells](/ton/cells/boc)** – TON’s universal data structure, used to represent every piece of information on-chain, from account states to transactions, in a compact and hash-friendly format.  
- - **[Addresses](/ton/addresses)** – The scheme TON uses to uniquely identify accounts and smart contracts across workchains and shardchains, with built-in error detection.  
+ - **[Addresses](/ton/addresses/addresses-general-info)** – The scheme TON uses to uniquely identify accounts and smart contracts across workchains and shardchains, with built-in error detection.  
- - **[Blocks](/ton/)** – The structure of TON blocks, which record the results of transactions and link shardchains together through cryptographic proofs.  
+ - **[Blocks](/ton/tbl)** – The structure of TON blocks, which record the results of transactions and link shardchains together through cryptographic proofs.  
- - **[TVM Whitepaper](/ton/wtvm)** – The original specification of the TON Virtual Machine, the execution engine for all smart contracts.  
+ - **[TVM Whitepaper](/ton/tvm)** – The original specification of the TON Virtual Machine, the execution engine for all smart contracts.  

Medium (5)

Click to expand

[MEDIUM] Headings not in sentence case (and ampersand)

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/0b23f298cdfd10500377b2accf8338ba819a28e6/ton/overview.mdx?plain=1#L11-L11

Description:
Headings use Title Case, and one uses “&”. Per the style guide, headings should use sentence case and avoid ampersands for clarity and consistency. This affects multiple section headers across the page, reducing visual consistency and scannability.

Suggestion:
Convert headings to sentence case and replace “&” with “and”.

-## Core Data Structures & Addressing
+## Core data structures and addressing
-## Transaction Processing
+## Transaction processing
-## Network Architecture
+## Network architecture
-## Validation & Security
+## Validation and security
-## Technical Whitepapers
+## Technical whitepapers
-## Reference Materials
+## Reference materials

[MEDIUM] Weak opener and missing acronym expansion

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/0b23f298cdfd10500377b2accf8338ba819a28e6/ton/overview.mdx?plain=1#L5-L5

Description:
The first sentence is a throat‑clearing opener (“This section introduces…”) and does not expand TON on first mention. The style guide prefers answer‑first openings and expanding acronyms on first use for clarity. Tightening the opener and adding the expansion improves readability for new readers.

Suggestion:
Revise the opener to be concise and expand the acronym.

-This section introduces the core concepts of the TON Blockchain. It explains the fundamental building blocks of the system, including data structures, transaction flow, consensus mechanisms, and network protocols.  
+Core concepts of The Open Network (TON): data structures, transaction flow, consensus, and networking.

[MEDIUM] Acronyms (ADNL, RLDP, DHT) not expanded on first mention

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/0b23f298cdfd10500377b2accf8338ba819a28e6/ton/overview.mdx?plain=1#L27-L27

Description:
The “Network Protocols” bullet introduces ADNL, RLDP, and DHT without expanding them on first mention. The style guide requires spelling out the term followed by the acronym in parentheses on first use. Without expansion, newcomers may not understand the references.

Suggestion:
Expand each acronym inline on first mention.

- - **[Network Protocols](/ton/network)** – TON’s communication stack, including ADNL for peer discovery, RLDP for reliable data transfer, and DHT for distributed lookups.  
+ - **[Network Protocols](/ton/network)** – TON’s communication stack, including Abstract Datagram Network Layer (ADNL) for peer discovery, Reliable Large Datagram Protocol (RLDP) for reliable data transfer, and distributed hash table (DHT) for distributed lookups.  

[MEDIUM] BFT acronym used before definition

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/0b23f298cdfd10500377b2accf8338ba819a28e6/ton/overview.mdx?plain=1#L40-L40

Description:
The “Catchain Consensus Whitepaper” bullet uses “BFT” without a prior on‑page acronym definition. Per the style guide, the first occurrence must spell out the term followed by the acronym in parentheses. Define “Byzantine fault‑tolerant (BFT)” at the earlier consensus bullet so the later usage is clear.

Suggestion:
Define the acronym on first conceptual mention (consensus bullet at L33).

- - **[Consensus](/ton/consensus)** – TON’s Catchain consensus protocol, a Byzantine Fault Tolerant algorithm that ensures validators reach agreement on blocks in the presence of faulty or malicious participants.  
+ - **[Consensus](/ton/consensus)** – TON’s Catchain consensus protocol, a Byzantine fault-tolerant (BFT) algorithm that ensures validators reach agreement on blocks in the presence of faulty or malicious participants.  

[MEDIUM] Non‑canonical casing for WorkChain/ShardChain

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/0b23f298cdfd10500377b2accf8338ba819a28e6/ton/overview.mdx?plain=1#L14-L14

Description:
The text uses lowercase “workchains” and “shardchains” in L14 and again later, but the term bank requires canonical casing for these TON‑specific proper nouns. Using the correct casing improves consistency and searchability across the docs. Additional occurrences appear at L25 and L28.

Suggestion:
Use the canonical casing across mentions.

- - **[Addresses](/ton/addresses/addresses-general-info)** – The scheme TON uses to uniquely identify accounts and smart contracts across workchains and shardchains, with built-in error detection.  
+ - **[Addresses](/ton/addresses/addresses-general-info)** – The scheme TON uses to uniquely identify accounts and smart contracts across WorkChains and ShardChains, with built-in error detection.  
@@
- - **[Blockchain Sharding](/ton/shards)** – TON’s horizontal scaling model, where every workchain is divided into multiple shardchains that can process transactions in parallel.  
+ - **[Blockchain Sharding](/ton/shards)** – TON’s horizontal scaling model, where every WorkChain is divided into multiple ShardChains that can process transactions in parallel.  
@@
- - **[Blocks](/ton/tbl)** – The structure of TON blocks, which record the results of transactions and link shardchains together through cryptographic proofs.  
+ - **[Blocks](/ton/tbl)** – The structure of TON blocks, which record the results of transactions and link ShardChains together through cryptographic proofs.  

Low (3)

Click to expand

[LOW] Generic capitalization and missing hyphen in “Byzantine fault‑tolerant”

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/0b23f298cdfd10500377b2accf8338ba819a28e6/ton/overview.mdx?plain=1#L33-L33

Description:
“Byzantine Fault Tolerant algorithm” capitalizes a generic descriptor and omits the conventional hyphen, which is inconsistent with standard usage. Use “Byzantine fault‑tolerant” mid‑sentence. This improves readability and correctness.

Suggestion:
Lowercase the generic words and hyphenate “fault‑tolerant”.

- - **[Consensus](/ton/consensus)** – TON’s Catchain consensus protocol, a Byzantine Fault Tolerant algorithm that ensures validators reach agreement on blocks in the presence of faulty or malicious participants.  
+ - **[Consensus](/ton/consensus)** – TON’s Catchain consensus protocol, a Byzantine fault‑tolerant algorithm that ensures validators reach agreement on blocks in the presence of faulty or malicious participants.  

[LOW] Mid‑sentence capitalization in link text

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/0b23f298cdfd10500377b2accf8338ba819a28e6/ton/overview.mdx?plain=1#L25-L27

Description:
Several link texts capitalize generic concepts mid‑sentence (e.g., “Blockchain Sharding”, “Node Configuration”, “Network Protocols”). The style guide requires sentence case for generic concepts to improve consistency and readability. Similar capitalization occurs elsewhere (e.g., L13–L15, L19–L21).

Suggestion:
Use sentence case for link text (apply similarly to other bullets).

- - **[Blockchain Sharding](/ton/shards)** – TON’s horizontal scaling model, where every workchain is divided into multiple shardchains that can process transactions in parallel.  
+ - **[Blockchain sharding](/ton/shards)** – TON’s horizontal scaling model, where every workchain is divided into multiple shardchains that can process transactions in parallel.  
- - **[Node Configuration](/ton/config)** – The setup of different TON node types, such as validators, liteservers, and full nodes, and how they cooperate to maintain the network.  
+ - **[Node configuration](/ton/config)** – The setup of different TON node types, such as validators, liteservers, and full nodes, and how they cooperate to maintain the network.  
- - **[Network Protocols](/ton/network)** – TON’s communication stack, including ADNL for peer discovery, RLDP for reliable data transfer, and DHT for distributed lookups.  
+ - **[Network protocols](/ton/network)** – TON’s communication stack, including ADNL for peer discovery, RLDP for reliable data transfer, and DHT for distributed lookups.  

[LOW] Prefer relative internal links

Location: https://github.com/tact-lang/mintlify-ton-docs/blob/0b23f298cdfd10500377b2accf8338ba819a28e6/ton/overview.mdx?plain=1#L19-L21

Description:
Internal links use site‑absolute paths (e.g., “/ton/transaction”). The style guide recommends relative links to avoid domain coupling and improve link stability within the docs. Converting to relative paths from ton/overview.mdx maintains correct navigation without relying on absolute routing.

Suggestion:
Switch to relative paths for the nearby links (apply similarly across the file).

- - **[Messages and Transactions](/ton/transaction)** – TON is message-driven: all interactions between accounts are handled through internal and external messages, which together form transactions.  
+ - **[Messages and transactions](transaction)** – TON is message-driven: all interactions between accounts are handled through internal and external messages, which together form transactions.  
- - **[Execution Phases and Fees](/ton/phases-and-fees)** – How TON processes a transaction through the Storage, Credit, Compute, Action, and Bounce phases, while applying gas and storage fees at each step.  
+ - **[Execution phases and fees](phases-and-fees)** – How TON processes a transaction through the Storage, Credit, Compute, Action, and Bounce phases, while applying gas and storage fees at each step.  
- - **[Precompiled Contracts](/ton/precompiled)** – Special smart contracts built into the TON protocol, optimized for frequently used cryptographic and system operations.  
+ - **[Precompiled contracts](precompiled)** – Special smart contracts built into the TON protocol, optimized for frequently used cryptographic and system operations.  

[Shvandre]

@fakela There is a LOT of inaccuracies in this article. I will fix all of them right here in your PR and merge. Please do not vibecode more)