[Tolk] New docs: overview page (landing)

Author: tolk-vm

contract-dev/first-smart-contract.mdx

@@ -118,7 +118,7 @@ First, we need a way to store the counter value. Tolk makes this simple with <To
 
 ```tolk title="./contracts/first_contract.tolk"
 struct Storage {
-    counter: uint64; // the current counter value
+    counter: uint64  // the current counter value
 }
 
 // load contract data from persistent storage
@@ -153,17 +153,17 @@ Tolk structures are also useful for defining message bodies. In our case, we’l
 Each structure has a unique prefix (`0x7e8764ef` and `0x3a752f06`), widely called opcodes, that lets the contract distinguish between them.
 
 ```tolk title="./contracts/first_contract.tolk"
-struct(0x7e8764ef) IncreaseCounter {
+struct (0x7e8764ef) IncreaseCounter {
     increaseBy: uint32
 }
 
-struct(0x3a752f06) ResetCounter {}
+struct (0x3a752f06) ResetCounter {}
 ```
 
 To group them together, we'll use a union. Unions allow multiple types to be bundled into a single type that can be serialized and deserialized automatically:
 
 ```tolk title="./contracts/first_contract.tolk"
-type AllowedMessage = IncreaseCounter | ResetCounter;
+type AllowedMessage = IncreaseCounter | ResetCounter
 ```
 
 Now we can write our message handler:
@@ -227,7 +227,7 @@ Here’s the full source code of `contracts/first_contract.tolk`:
 
 ```tolk title="./contracts/first_contract.tolk" expandable
 struct Storage {
-    counter: uint64;
+    counter: uint64
 }
 
 fun Storage.load() {
@@ -238,13 +238,13 @@ fun Storage.save(self) {
     contract.setData(self.toCell());
 }
 
-struct(0x7e8764ef) IncreaseCounter {
+struct (0x7e8764ef) IncreaseCounter {
     increaseBy: uint32
 }
 
-struct(0x3a752f06) ResetCounter {}
+struct (0x3a752f06) ResetCounter {}
 
-type AllowedMessage = IncreaseCounter | ResetCounter;
+type AllowedMessage = IncreaseCounter | ResetCounter
 
 fun onInternalMessage(in: InMessage) {
     val msg = lazy AllowedMessage.fromSlice(in.body);

languages/func/overview.mdx

@@ -7,7 +7,7 @@ noindex: "true"
 import { Aside } from '/snippets/aside.jsx';
 
 <Aside>
-  TON Blockchain uses Tolk as the official language. Other languages are still available, and legacy codebases exist, but Tolk is the only actively supported language. The FunC compiler, for instance, is no longer maintained.
+  TON Blockchain uses [Tolk](/languages/tolk) as the official language. Other languages are still available, and legacy codebases exist, but Tolk is the only actively supported language. The FunC compiler, for instance, is no longer maintained.
 </Aside>
 
 FunC is a domain-specific, statically typed language with C-like syntax designed to write smart contracts on TON. It can be characterized as an intermediate-level language sitting on top of the [Fift](/languages/fift) assembly language.

languages/tolk/overview.mdx

@@ -1,115 +1,96 @@
 ---
-title: "Tolk"
+title: "Tolk — the language for TON"
 sidebarTitle: "Overview"
 ---
 
-**Tolk** is a next-generation language for developing smart contracts on TON. It replaces FunC with an expressive syntax, a robust type system, and built-in serialization — while generating highly optimized assembly code.
+import { Aside } from '/snippets/aside.jsx';
 
-This page introduces Tolk's _core features, explains how it compares to FunC, and outlines how to get started with the language_ — whether you're migrating from FunC or writing smart contracts from scratch.
+**Tolk** is a statically typed language designed for TON smart contracts.
 
-## Why choose Tolk
+It provides declarative structures, automatic cell serialization, first-class message handling, and a modern development experience.
 
-1. Clean, expressive syntax inspired by TypeScript and Rust.
-1. Built-in primitives for TON, including structures, auto‑packing to/from cells, pattern matching, and first-class message handling.
-1. Strong static type system with _null safety, type aliases, union types, and generics_ for safer, clearer code.
-1. Gas‑efficient by design — see [benchmarks](https://github.com/ton-blockchain/tolk-bench) and [comparison](/languages/tolk/from-func/tolk-vs-func); features like **[Lazy loading](/languages/tolk/features/lazy-loading)** can reduce costs.
-1. Low-level control is available when needed, with direct access to the TVM stack and instructions.
-
-## Getting started with Tolk
-
-To get familiar with Tolk, follow the ["Your first smart contract"](/contract-dev/first-smart-contract) article.
-It contains required steps for setting up an environment and creating a counter contract from a template, as well as explanation of every step.
-
-Later on, return to this section and start exploring [Basic syntax](/languages/tolk/basic-syntax), [Type system](/languages/tolk/types/list-of-types),
-and other points from the left menu.
-
-## How to migrate from FunC
-
-If you've written contracts in FunC, migrating to Tolk is straightforward — and often results in simpler, more maintainable code.
-
-1. Try building a basic contract in Tolk — for example, a counter using `npm create ton@latest`. You'll quickly notice the shift from stack logic to expressive constructs with structured types, unions, pattern matching, `toCell()`, and more.
-1. Explore the [Tolk vs FunC benchmarks](https://github.com/ton-blockchain/tolk-bench). These are real-world contracts (Jetton, NFT, Wallet, etc.) migrated from FunC — same logic, but expressed in a cleaner, more expressive style.
-1. Read [Tolk vs FunC](/languages/tolk/from-func/tolk-vs-func) for a quick comparison of syntax and concepts.
-1. Use the [FunC-to-Tolk converter](/languages/tolk/from-func/converter) to migrate existing codebases incrementally.
-
-## Example of a basic Tolk smart contract:
+The language compiles to TVM (TON virtual machine) with zero overhead and full control over execution.
 
 ```tolk
-import "utils"
-
-struct Storage {
-    counter: int32
-}
-
-fun Storage.load() {
-    return Storage.fromCell(contract.getData());
-}
+type AllowedMessage = CounterIncrement | CounterReset
 
 fun onInternalMessage(in: InMessage) {
-    // ...
+    val msg = lazy AllowedMessage.fromSlice(in.body);
+    match (msg) {
+        CounterIncrement => { ... }
+        CounterReset => { ... }
+    }
 }
 
-get fun currentCounter(): int {
+get fun currentCounter() {
     val storage = lazy Storage.load();
     return storage.counter;
 }
 ```
 
-<details>
-  <summary><b>Equivalent implementation in FunC</b></summary>
+## Key features
 
-  ```func
-  #include "utils.fc";
+Tolk offers high-level readability while remaining low-level in nature:
 
-  global int ctx_counter;
+- a robust type system to express any cell layout in TON
+- lazy loading: unused fields are skipped automatically
+- unified message composition and deployment
+- a gas-efficient compiler targeting the Fift assembler
+- friendly tooling and IDE integration
 
-  int load_data() impure {
-    slice cs = get_data().begin_parse();
-    ctx_counter = cs~load_uint(32);
-  }
+<Aside type="tip">
+  Tolk is fully compatible with existing TON standards and contracts.
+</Aside>
 
-  () recv_internal(int msg_value, cell msg_full, slice msg_body) impure {
-    slice cs = msg_full.begin_parse();
-    int flags = cs~load_uint(4);
-    if (flags & 1) {
-      return ();
-    }
-    ...
-  }
+## Tolk is a replacement for FunC
+
+Tolk started as an evolution of FunC and is now the recommended language for TON smart contracts.
+
+If you are migrating from FunC:
+
+- Look through [benchmarks](https://github.com/ton-blockchain/tolk-bench): notice **30–50% lower gas fees**.
+- Scan the page [Tolk vs FunC](/languages/tolk/from-func/tolk-vs-func) to get the overall picture.
+- Use the [FunC-to-Tolk converter](/languages/tolk/from-func/converter) to migrate existing projects.
+
+## Quick start
+
+1. Run the command:
 
-  int currentCounter() method_id {
-    load_data(); ;; fills global variables
-    return ctx_counter;
-  }
-  ```
-</details>
+   ```bash
+   npm create ton@latest
+   ```
 
-[FunC to Tolk converter](https://github.com/ton-blockchain/convert-func-to-tolk).
+1. Enter a project name and choose "simple counter contract".
 
-## Tooling around Tolk
+1. Follow the ["Your first smart contract"](/contract-dev/first-smart-contract) article
+   to get explanations.
 
-A set of tools is available to support development with Tolk — including IDE support, language services, and migration utilities.
+## IDE support
 
-- [JetBrains IDE plugin](https://github.com/ton-blockchain/intellij-ton). Adds support for Tolk, FunC, Fift, and TL-B.
-- [VS Code extension](https://marketplace.visualstudio.com/items?itemName=ton-core.vscode-ton). Provides Tolk support and language features.
-- [Language server](https://github.com/ton-blockchain/ton-language-server). Works with any LSP-compatible editor.
-- [FunC-to-Tolk converter](https://github.com/ton-blockchain/convert-func-to-tolk). Migrates entire projects with a single `npx` command.
-- [`tolk-js`](https://github.com/ton-blockchain/tolk-js). WASM wrapper for the Tolk compiler is integrated into Blueprint.
+All major IDEs support syntax highlighting and code completion:
 
-The Tolk compiler itself lives in the `ton` [repository](https://github.com/ton-blockchain/ton).
+1. **JetBrains IDEs** (WebStorm, CLion, etc.) — via the [plugin](https://github.com/ton-blockchain/intellij-ton)<br />
+   \=> search for "TON" in Marketplace and install
 
-## Is Tolk production-ready?
+1. **VS Code** — via the [TON extension](https://marketplace.visualstudio.com/items?itemName=ton-core.vscode-ton)<br />
+   \=> search for "TON" in Marketplace and install
 
-All contracts in the [Tolk vs FunC benchmarks](https://github.com/ton-blockchain/tolk-bench) pass the same test suites as their FunC counterparts — with identical logic and behavior.
+1. **Cursor, Windsurf, and other** editors — via the [language server](https://github.com/ton-blockchain/ton-language-server)<br />
+   \=> install from the `.vsix` file or a command palette
 
-Tolk is under active development, and some edge cases may still occur. Evaluate it for your use case and ensure thorough testing before production deployment.
+## Where to go next
 
-Regardless of the language, well-tested code is the key to building reliable smart contracts.
+Recommended starting points:
 
-## Issues and contacts
+- [Basic syntax](/languages/tolk/basic-syntax)
+- [Idioms and conventions](/languages/tolk/idioms-conventions)
+- [Type system](/languages/tolk/types/list-of-types)
+- [Message handling](/languages/tolk/features/message-handling)
 
-If you encounter an issue, please connect with the developer community on [TON Dev chats](https://t.me/addlist/1r5Vcb8eljk5Yzcy) or create a [GitHub issue](https://github.com/ton-community/ton-docs/issues).
+## External resources
 
-## See also
+Useful links outside this documentation:
 
-- [Tolk vs FunC](/languages/tolk/from-func/tolk-vs-func)
+- [TON Dev chats](https://t.me/addlist/1r5Vcb8eljk5Yzcy) in Telegram
+- [@tolk\_lang channel](https://t.me/tolk_lang) in Telegram
+- [GitHub](https://github.com/ton-blockchain/ton) for issues and sources