diff --git a/packages/client/README.md b/packages/client/README.md
new file mode 100644
index 00000000..b11abacb
--- /dev/null
+++ b/packages/client/README.md
@@ -0,0 +1,35 @@
+# @mtcute/client
+
+📖 [API Reference](https://ref.mtcute.dev/modules/_mtcute_client.html)
+
+High-level Telegram client implementation over the `@mtcute/core` base library.
+
+## Features
+- **Updates handling**: Implements proper updates handling, including ordering and gap recovery ([learn more](https://core.telegram.org/api/updates))
+- **Wrapper classes**: Easy-to-use classes that wrap the complex TL objects and provide a clean interface
+- **High-level methods**: Methods that wrap the low-level API calls and provide a clean interface
+- **Tree-shaking**: Only import the methods you need, and the rest will not be included into the bundle
+- **Web support**: Works in the browser with no additional configuration
+
+## Usage
+
+```ts
+import { TelegramClient } from '@mtcute/client'
+
+const tg = new TelegramClient({
+    apiId: 12345,
+    apiHash: '0123456789abcdef0123456789abcdef',
+    // ... + supports all options from @mtcute/core ...
+})
+
+tg.start({
+    phone: '+1234567890',
+    password: () => prompt('Enter password'),
+    code: () => prompt('Enter code'),
+}, (user) => {
+    console.log(`Logged in as ${user.displayName}`)
+})
+```
+
+> **Note**: for web, prefer BaseTelegramClient over TelegramClient, 
+> as it is tree-shakeable – [learn more](https://mtcute.dev/guide/topics/treeshaking.html)
diff --git a/packages/core/README.md b/packages/core/README.md
index 83ffd449..b651d5f3 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -1,5 +1,26 @@
-# `@mtcute/core`
+# @mtcute/core
 
-Core functions and MTProto implementation.
+📖 [API Reference](https://ref.mtcute.dev/modules/_mtcute_core.html)
 
-You can learn more in [the guide](/guide/index.html).
+Basic low-level MTProto implementation and auxiliary utilities.
+
+## Features
+- **MTProto 2.0**: Implements the full MTProto protocol, including all the encryption and serialization
+- **2FA support**: Provides utilities for 2-step verification
+- **Hackable**: Bring your own storage, transport, and other components to customize the library to your needs
+- **Magical**: Handles reconnections, connection pooling, DC redirections and other stuff for you
+- **Web support**: Works in the browser with no additional configuration
+
+## Usage
+
+```ts
+import { BaseTelegramClient } from '@mtcute/core'
+
+const tg = new BaseTelegramClient({
+    apiId: 12345,
+    apiHash: '0123456789abcdef0123456789abcdef',
+})
+
+tg.call({ _: 'help.getConfig' })
+    .then(console.log)
+```
diff --git a/packages/create-bot/README.md b/packages/create-bot/README.md
index 7a7106e3..719436f8 100644
--- a/packages/create-bot/README.md
+++ b/packages/create-bot/README.md
@@ -2,8 +2,17 @@
 
 Starter kit for creating bots using `@mtcute/node`.
 
+[Learn more](https://mtcute.dev/guide/)
+
+## Features
+- **Linters**: can generate linting configs for `eslint` and `prettier`
+- **TypeScript**: can generate a TypeScript project
+- **Docker**: can generate a Dockerfile for easy deployment
+- **I18n**: can generate a basic i18n setup using `@mtcute/i18n`
+
 ## Usage
 
 ```bash
 pnpm create @mtcute/bot
+# and follow the instructions
 ```
diff --git a/packages/crypto-node/README.md b/packages/crypto-node/README.md
index ffde5f12..d4f363a0 100644
--- a/packages/crypto-node/README.md
+++ b/packages/crypto-node/README.md
@@ -1,4 +1,6 @@
-# `@mtcute/crypto-node`
+# @mtcute/crypto-node
+
+📖 [API Reference](https://ref.mtcute.dev/modules/_mtcute_crypto_node.html)
 
 Native extension for NodeJS that improves performance of the most used
 cryptographic mode in Telegram (IGE), which is not implemented by OpenSSL.
@@ -24,5 +26,7 @@ const tg = new TelegramClient({
 })
 ```
 
+> **Tip**: When using `@mtcute/node`, this will be done automatically for you.
+
 ## Acknowledgments
 Based on [pyrogram/tgcrypto](https://github.com/pyrogram/tgcrypto)
diff --git a/packages/dispatcher/README.md b/packages/dispatcher/README.md
index 269972f3..1d92b832 100644
--- a/packages/dispatcher/README.md
+++ b/packages/dispatcher/README.md
@@ -1,5 +1,26 @@
-# `@mtcute/dispatcher`
+# @mtcute/dispatcher
 
-Dispatcher and bot framework for mtcute.
+📖 [API Reference](https://ref.mtcute.dev/modules/_mtcute_dispatcher.html)  
+🧐 [Guide](https://mtcute.dev/guide/dispatcher/intro.html)
 
-You can learn more in [the guide](/guide/index.html).
+Dispatcher and bot framework based on @mtcute/client.
+
+## Features
+- **Straightforward**: Simple and expressive API
+- **State**: Supports storing state for each chat
+- **Filters**: Powerful and easy-to-use filtering system
+- **Middleware**: Basic middleware support for updates
+- **Scenes**: Built-in support for scenes
+
+## Usage
+
+```ts
+import { NodeTelegramClient, Dispatcher } from '@mtcute/node'
+
+const tg = new NodeTelegramClient({ ... })
+const dp = Dispatcher.for(tg)
+
+dp.onNewMessage(async (msg) => {
+    await msg.replyText('Hello world!')
+})
+```
\ No newline at end of file
diff --git a/packages/file-id/README.md b/packages/file-id/README.md
index 30e6d09f..04e4929f 100644
--- a/packages/file-id/README.md
+++ b/packages/file-id/README.md
@@ -1,20 +1,11 @@
-# `@mtcute/file-id`
+# @mtcute/file-id
 
-A package that is used internally by `@mtcute/client` to parse, serialize
+📖 [API Reference](https://ref.mtcute.dev/modules/_mtcute_file_id.html)
+
+This package is used internally by `@mtcute/client` to parse, serialize
 and manipulate TDLib and Bot API compatible File IDs, but can also be used
 for any other purposes.
 
-## Contents
-This package exports a number of functions, namely:
- - `parseFileId()` which parses provided File ID to an object representing its contents
- - `toFileId()` which serializes provided object containing file info to a File ID
- - `toUniqueFileId()` which serializes provided object containing file info to a Unique File ID
- - `fileIdTo*()` which converts a File ID to an input TL object, which can be used
-   in RPC calls etc.
-
-This package also exports namespace `tdFileId`, which contains all the types
-used by the library
-
 ## Acknowledgements
 This is basically a port of a portion of TDLib APIs, but greatly
 simplified in usage and made to work seamlessly with the rest of the
diff --git a/packages/html-parser/README.md b/packages/html-parser/README.md
index cd28519c..07d1d918 100644
--- a/packages/html-parser/README.md
+++ b/packages/html-parser/README.md
@@ -1,17 +1,23 @@
 # @mtcute/html-parser
 
-> HTML entities parser for mtcute
+📖 [API Reference](https://ref.mtcute.dev/modules/_mtcute_html_parser.html)
 
-This package implements formatting syntax based on HTML, similar to the one available in the Bot
-API ([documented here](https://core.telegram.org/bots/api#html-style))
+
+HTML entities parser for mtcute
 
 > **NOTE**: The syntax implemented here is **incompatible** with Bot API _HTML_.
 >
 > Please read [Syntax](#syntax) below for a detailed explanation
 
+## Features
+- Supports all entities that Telegram supports
+- Supports nested entities
+- Proper newline handling (just like in real HTML)
+- Automatic escaping of user input
+
 ## Usage
 
-```typescript
+```ts
 import { TelegramClient } from '@mtcute/client'
 import { HtmlMessageEntityParser, html } from '@mtcute/html-parser'
 
@@ -73,9 +79,6 @@ Optionally, language for `<pre>` block can be specified like this:
 <pre language="typescript">export type Foo = 42</pre>
 ```
 
-> However, since syntax highlighting hasn't been implemented in
-> official Telegram clients except WebA, this doesn't really matter 🤷‍♀️
-
 | Code                                                                                | Result (visual)              |
 | ----------------------------------------------------------------------------------- | ---------------------------- |
 | <pre>&lt;pre&gt;multiline\ntext&lt;/pre&gt;</pre>                                   | <pre>multiline<br>text</pre> |
diff --git a/packages/http-proxy/README.md b/packages/http-proxy/README.md
index 923d4342..3d475499 100644
--- a/packages/http-proxy/README.md
+++ b/packages/http-proxy/README.md
@@ -1,5 +1,7 @@
 # @mtcute/http-proxy
 
+📖 [API Reference](https://ref.mtcute.dev/modules/_mtcute_http_proxy.html)
+
 HTTP(s) proxy transport for mtcute.
 
 ## Usage
diff --git a/packages/i18n/README.md b/packages/i18n/README.md
index e365b62c..45a34018 100644
--- a/packages/i18n/README.md
+++ b/packages/i18n/README.md
@@ -1,5 +1,39 @@
 # @mtcute/i18n
 
-This package implements utility for i18n functionality in `@mtcute/client` based apps.
+📖 [API Reference](https://ref.mtcute.dev/modules/_mtcute_i18n.html)
 
-Learn more in the [Guide](/guide/topics/i18n).
+Internationalization library built with TypeScript and mtcute in mind.
+
+## Features
+- **Type-safe**: All string keys and parameters are type-checked
+- **Plurals**: Supports pluralization
+- **Customizable**: Supports custom locales and customizing existing ones
+- **Pluggable**: Can be used with any library, not just mtcute. Can also be used with other i18n libraries.
+
+## Usage
+
+```ts
+// i18n/en.ts
+export const en = {
+    hello: (name: string) => `Hello, ${name}!`,
+}
+
+// i18n/ru.ts
+export const ru: OtherLanguageWrap<typeof en> = {
+    hello: (name: string) => `Привет, ${name}!`,
+}
+
+// i18n/index.ts
+export const tr = createMtcuteI18n({
+    primaryLanguage: {
+        name: 'en',
+        strings: en,
+    },
+    otherLanguages: { ru },
+})
+
+// main.ts
+dp.onNewMessage(async (upd) => {
+    await upd.replyText(tr(upd, 'hello', upd.sender.displayName))
+})
+```
diff --git a/packages/markdown-parser/README.md b/packages/markdown-parser/README.md
index b351434d..7e5939fa 100644
--- a/packages/markdown-parser/README.md
+++ b/packages/markdown-parser/README.md
@@ -1,13 +1,17 @@
 # @mtcute/markdown-parser
 
-> Markdown entities parser for mtcute
+📖 [API Reference](https://ref.mtcute.dev/modules/_mtcute_markdown_parser.html)
 
-This package implements formatting syntax similar to Markdown (CommonMark) but slightly adjusted and simplified.
+Markdown entities parser for mtcute
 
 > **NOTE**: The syntax implemented here is **not** compatible with Bot API _Markdown_, nor _MarkdownV2_.
 >
 > Please read [Syntax](#syntax) below for a detailed explanation
 
+> **Note**:
+> It is generally recommended to use `@mtcute/html-parser` instead, 
+> as it is easier to use and is more readable in most cases
+
 ## Usage
 
 ```typescript
@@ -123,9 +127,6 @@ To escape any character, prepend it with ` \ ` (backslash). Escaped characters a
 Inline entities and links inside code entities (both inline and pre) are not processed, so you only need to escape
 closing tags.
 
-Also, in JavaScript (and many other languages) ` \ ` itself must be escaped, so you'll end up with strings
-like `"\\_\\_not italic\\_\\_`.
-
 > **Note**: backslash itself must be escaped like this: ` \\ ` (double backslash).
 >
 > This will look pretty bad in real code, so use escaping only when really needed, and use
diff --git a/packages/mtproxy/README.md b/packages/mtproxy/README.md
index fc778ecb..16407331 100644
--- a/packages/mtproxy/README.md
+++ b/packages/mtproxy/README.md
@@ -1,7 +1,11 @@
 # @mtcute/mtproxy
 
+📖 [API Reference](https://ref.mtcute.dev/modules/_mtcute_mtproxy.html)
+
 MTProto proxy (MTProxy) transport for mtcute.
 
+Supports all kinds of MTProto proxies, including obfuscated and fake TLS.
+
 ## Usage
 
 ```typescript
diff --git a/packages/node/README.md b/packages/node/README.md
index b1e051ef..fbfec035 100644
--- a/packages/node/README.md
+++ b/packages/node/README.md
@@ -1,13 +1,11 @@
 # @mtcute/node
 
+📖 [API Reference](https://ref.mtcute.dev/modules/_mtcute_node.html)
+
 All-in-one package for NodeJS. Includes support for native crypto addon
 (must be installed separately, `@mtcute/crypto-node`), terminal I/O via
 `readline` and comes with pre-installed HTML and Markdown parsers.
 
-> **Note**: documentation for this package only includes changes from
-> `@mtcute/client`. For full documentation, see
-> [`@mtcute/client` docs](../client/index.html).
-
 ## Usage
 
 ```typescript
@@ -16,6 +14,6 @@ import { NodeTelegramClient } from '@mtcute/node'
 const tg = new NodeTelegramClient({
     apiId: 12345,
     apiHash: 'abcdef',
-    storage: 'client.session'
+    storage: 'my-account'
 })
 ```
diff --git a/packages/socks-proxy/README.md b/packages/socks-proxy/README.md
index da320daf..a883e3bc 100644
--- a/packages/socks-proxy/README.md
+++ b/packages/socks-proxy/README.md
@@ -1,5 +1,7 @@
 # @mtcute/socks-proxy
 
+📖 [API Reference](https://ref.mtcute.dev/modules/_mtcute_socks_proxy.html)
+
 Socks4/5 proxy transport for mtcute.
 
 ## Usage
diff --git a/packages/sqlite/README.md b/packages/sqlite/README.md
index d7b93447..abf522cb 100644
--- a/packages/sqlite/README.md
+++ b/packages/sqlite/README.md
@@ -1,6 +1,8 @@
 # @mtcute/sqlite
 
-SQLite backed storage for mtcute, based on `better-sqlite3`
+📖 [API Reference](https://ref.mtcute.dev/modules/_mtcute_sqlite.html)
+
+SQLite backed storage for mtcute, built with `better-sqlite3`
 
 ## Usage
 
diff --git a/packages/tl-runtime/README.md b/packages/tl-runtime/README.md
index 7a78a8dc..652bc408 100644
--- a/packages/tl-runtime/README.md
+++ b/packages/tl-runtime/README.md
@@ -1,9 +1,16 @@
 # @mtcute/tl-runtime
 
+📖 [API Reference](https://ref.mtcute.dev/modules/_mtcute_tl_runtime.html)
+
 This package contains runtime for TL (de-)serialization.
 It only contains binary reader and writer implementations,
-and is used by `@mtcute/core`.
+as well as some `Uint8Array` utilities, and is used by `@mtcute/core`.
 
 `@mtcute/tl-utils` on the other hand has utilities like codegen
 and schema manipulation, which is only needed at runtime if you
 are patching the schema (which is a rare case anyways).
+
+## Features
+- Supports all TL features used by the public schema
+- Uint8Array utilities like `hexDecode`
+- Supports browsers out of the box
\ No newline at end of file
diff --git a/packages/tl-utils/README.md b/packages/tl-utils/README.md
index a948438f..d6509ac9 100644
--- a/packages/tl-utils/README.md
+++ b/packages/tl-utils/README.md
@@ -1,8 +1,12 @@
 # @mtcute/tl-utils
 
-This package contains utilities for TL schema parsing and manipulation:
-  - Parsing & generating TL schema definitions
-  - Computing constructor IDs
-  - Parsing & generating TDLib style comments
-  - Code generation for readers and writers maps, errors, type definitions
-  - Merging and diffing entries, schemas
+📖 [API Reference](https://ref.mtcute.dev/modules/_mtcute_tl_utils.html)
+
+Utilities for TL schema parsing and manipulation
+
+## Features
+- Parsing & generating TL schema definitions
+- Computing constructor IDs
+- Parsing & generating TDLib style comments
+- Code generation for readers and writers maps, errors, type definitions
+- Merging and diffing entries, schemas
diff --git a/packages/tl/README.md b/packages/tl/README.md
index 559e82c3..57d22cba 100644
--- a/packages/tl/README.md
+++ b/packages/tl/README.md
@@ -1,6 +1,6 @@
 # @mtcute/tl
 
-> TL schema and related utils used for mtcute.
+TL schema and related utils used for mtcute.
 
 Generated from TL layer **166** (last updated on 29.10.2023).
 
@@ -12,27 +12,25 @@ Package's major version is always TL schema layer number,
 so version `42.0.0` means that this version was generated from TL layer 42.
 
 - JSON schema, types, binary (de-)serialization and helper functions are generated directly from `.tl` files that are
-  automatically fetched from [TDesktop repository](https://github.com/telegramdesktop/tdesktop/).
-- Errors are generated
-  from [`errors.csv`](https://github.com/LonamiWebs/Telethon/blob/master/telethon_generator/data/errors.csv)
-  that is automatically fetched from [Telethon repository](https://github.com/LonamiWebs/Telethon).
+  automatically fetched from multiple sources and are merged together.
+- Errors are generated from 
+  [`errors.csv`](https://github.com/LonamiWebs/Telethon/blob/master/telethon_generator/data/errors.csv)
+  and official Telegram errors JSON file.
 - RSA keys info is generated based on manually extracted PEMs from Telegram for Android source code.
 
-## Contents
+## Exports
 
-### `@mtcute/tl`
-
-[Documentation](./modules/index.html)
+### Root
 
 TypeScript typings and type helpers generated from the schema.
 
 By default, all types are immutable (have their fields marked as `readonly`). That is because most of the time you don't
 really need to modify the objects, and modifying them will only lead to confusion. However, there are still valid
 use-cases for mutable TL objects, so you can use exported
-`tl.Mutable` type to make a given object type mutable.
+`tl.Mutable` helper type to make a given object type mutable.
 
-`tl` is exported as a namespace to allow better code insights, and to avoid cluttering global namespace and very long
-import statements.
+`tl` is exported as a namespace to allow better code insights, 
+as well as to avoid cluttering global namespace and very long import statements.
 
 MTProto schema is available in namespace `mtp`, also exported by this package.
 
@@ -56,7 +54,7 @@ try {
 }
 ```
 
-### `@mtcute/tl/api-schema`
+### `/api-schema.json`
 
 [Documentation](./modules/api_schema.html)
 
@@ -64,38 +62,42 @@ JSON file describing all available TL classes, methods and unions. Can be used t
 > This very file is used to generate binary serialization and TypeScript typings for `@mtcute/tl`.
 
 ```typescript
-import * as tlSchema from '@mtcute/tl/raw-schema'
+import * as tlSchema from '@mtcute/tl/raw-schema.json'
+
 console.log(`Current layer: ${tlSchema.apiLayer}`)
 // Current layer: 124
 ```
 
-### `@mtcute/tl/binary/reader`
-
-[Documentation](./modules/binary_reader.html)
+### `/binary/reader.js`
 
 Contains mapping used to read TL objects from binary streams.
 
 ```typescript
-import readerMap from '@mtcute/tl/binary/reader'
-import { BinaryReader } from './binary-reader'
+import { __tlReaderMap } from '@mtcute/tl/binary/reader.js'
+import { TlBinaryReader } from '@mtcute/tl-runtime'
 
-const reader = new BinaryReader(Buffer.from([...]))
-console.log(readerMap[0x5bb8e511 /* mt_message */].call(reader))
+const reader = TlBinaryReader.manual(new Uint8Array([...]))
+console.log(readerMap[0x5bb8e511 /* mt_message */](reader))
 // { _: 'mt_message', ... }
 ```
 
-### `@mtcute/tl/binary/writer`
-
-[Documentation](./modules/binary_writer.html)
+### `/binary/writer.js`
 
 Contains mapping used to write TL objects to binary streams.
 
 ```typescript
-import writerMap from '@mtcute/tl/binary/writer'
-import { BinaryWriter } from './binary-writer'
+import { __tlWriterMap } from '@mtcute/tl/binary/writer'
+import { TlBinaryWriter } from '@mtcute/tl-runtime'
 
-const writer = new BinaryWriter()
-writerMap[0x5bb8e511 /* mt_message */].call(writer, { ... })
+const writer = TlBinaryWriter.manual(100)
+writerMap[0x5bb8e511 /* mt_message */](writer, { ... })
 console.log(writer.result())
-// Buffer <11 e5 b8 5b ...>
+// Uint8Array <11 e5 b8 5b ...>
 ```
+
+### `/binary/rsa-keys.js`
+
+Contains RSA keys used when authorizing with Telegram.
+
+`old` flag also determines if the client should use the old
+RSA padding scheme.
\ No newline at end of file