diff --git a/.gitignore b/.gitignore
index 0534114d..e0534f62 100644
--- a/.gitignore
+++ b/.gitignore
@@ -23,6 +23,4 @@ yarn-error.log*
 
 .claude
 
-CLAUDE.md
-
 .omc
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..dd3d5fa6
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,92 @@
+# AGENTS.md
+
+Agent guide for the ScriptCat documentation site (docs.scriptcat.org). Human contributors should start with [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+> Note on language: this file is in English. [CONTRIBUTING.md](./CONTRIBUTING.md) and [agents/i18n.md](./agents/i18n.md) are written in Chinese with an English summary at the top — read that summary line first if you only need the gist.
+
+## Project overview
+
+The official documentation and marketing site for ScriptCat, a browser extension that runs user scripts. Stack: Docusaurus 3, React 18, TypeScript, Tailwind CSS, Ant Design.
+
+Package manager is **pnpm** (v10.9.0). Node.js >= 18.
+
+## Commands
+
+```bash
+pnpm i                       # Install dependencies
+pnpm run start               # Dev server (Chinese, default locale)
+pnpm run start:en            # Dev server (English, port 3001)
+pnpm run start:ru            # Dev server (Russian, port 3002)
+pnpm run build               # Production build (builds every locale in one pass)
+pnpm run serve               # Serve the production build locally
+pnpm run typecheck           # TypeScript type checking
+pnpm run check               # URL contract / fallback output / i18n parity / frontmatter
+pnpm run write-translations  # Scaffold i18n translation files
+```
+
+## Before you commit
+
+`.gitea/workflows/ci.yaml` runs `pnpm run typecheck && pnpm run build && pnpm run check` on every PR, and `deploy.yaml` runs `build && check` again before shipping. CI lives on Gitea, so GitHub shows no status checks — that does **not** mean there is no CI. Run this locally at minimum:
+
+```bash
+pnpm run typecheck && pnpm run build && pnpm run check
+```
+
+Three things to know:
+
+- **`pnpm run check` needs the `build/` output** (`check:fallbacks` reads the generated HTML), so build first.
+- **Do not build a single locale only.** `onBrokenLinks` and `onBrokenAnchors` are both `throw`, but a broken link or anchor only surfaces in the locale that contains it — `--locale zh-Hans` alone misses English and Russian breakage.
+- After touching anything in `src/`, spot-check a page in `build/`, `build/en/` **and** `build/ru/`. Verifying only the Chinese output is how most of this repo's localization bugs got through.
+
+## Hard constraints
+
+1. **These URLs are hardcoded by the browser extension and must never change**: `/docs/script_installation/`, `/docs/use/install_comple/` (`install_comple` is a legacy spelling, deliberately kept — not a typo), `/uninstall/`. `scripts/url-inventory.txt` is the committed route baseline and `check:urls` diffs against it.
+2. **Intentional new routes** must update that baseline in the same PR via `node scripts/check-url-inventory.mjs --write`, so reviewers can see what you added on purpose.
+3. **Never put non-documentation markdown under `docs/`.** `docs/` is the published tree: a new `.md` there creates a public route, requires a mirror in every locale, and requires `title:` frontmatter — it trips `check:urls`, `check:i18n` and `check:frontmatter` at once. Repo-internal docs belong in `agents/` or the repo root.
+4. **Never assume the site has only Chinese and English.** There are three locales; see below.
+
+## Layout
+
+| Path | What it is |
+|---|---|
+| `docusaurus.config.js` | Site config (i18n, navbar, footer, Algolia, GA, per-locale SEO metadata) |
+| `sidebars.js` | Three sidebars (`use`/`dev`/`change`), all explicit lists |
+| `docs/` | Chinese docs (default locale). Three sections: `use/` guides, `dev/` API docs, `change/` changelogs |
+| `i18n/<locale>/` | Per-locale doc mirrors and UI strings |
+| `src/pages/` | Custom pages (`index.tsx` landing page, `uninstall.tsx` feedback survey) |
+| `src/components/landing/` | Landing page sections (`sections.tsx`, `LandingNav.tsx`, `shared.tsx`) |
+| `src/theme/` | Docusaurus theme overrides (custom `Footer`, `Root` language-detection redirect) |
+| `src/service/` | API layer (calls `https://scriptcat.org/api/v2`) |
+| `scripts/` | Check scripts, `check-config.json`, `url-inventory.txt` route baseline |
+| `deploy/` | Dockerfile, nginx config, Helm chart |
+| `agents/` | Detailed conventions written for agents |
+
+## Localization (read before touching i18n code)
+
+Three locales: `zh-Hans` (default, no URL prefix), `en` (`/en/`), `ru` (`/ru/`).
+
+The four mistakes that keep recurring — **full rules and incident notes in [agents/i18n.md](./agents/i18n.md)**:
+
+1. **Hardcoding a locale name.** `currentLocale !== "en"` or `pathname.startsWith("/en/")` classifies Russian as Chinese; building a prefix without stripping the existing one produces `/en/ru/x` (a 404). Read the locale from `useDocusaurusContext().i18n.currentLocale`; iterate with `i18n.locales` and `i18n.localeConfigs`.
+2. **Forgetting baseUrl on a plain `<a href="/...">`.** For non-default locales `baseUrl` is `/en/` or `/ru/`. `<Link to>` and markdown links apply it automatically; plain `<a>` and antd `<Button href>` do not — wrap those in `withBaseUrl()`.
+3. **Hardcoded UI copy.** Everything user-facing goes through `<Translate>` / `translate()`, with keys added to both `i18n/en/code.json` and `i18n/ru/code.json` (identical key count **and** order).
+4. **Locale assumptions outside `src/`.** `docusaurus.config.js`'s `metadataByLocale` and `deploy/docker/nginx.conf`'s 404 routing both enumerate locales by hand and must be updated when adding a language. The nginx one is invisible to the build and to `pnpm run check` — it only shows up in production.
+
+Changelogs under `change/` are not translated into Russian: the Russian routes compile the English doc tree directly (`docusaurus.config.js` swaps `docs.path` based on `DOCUSAURUS_CURRENT_LOCALE`). **That fallback covers the whole tree**, so any file missing under `i18n/ru/` silently renders in English instead of failing the build — only `check:i18n` catches it. Do not skip `pnpm run check`.
+
+## Styling
+
+- Tailwind CSS via `@gracefullight/docusaurus-plugin-tailwind`
+- Component-scoped styles via CSS Modules (`.module.css`)
+- Theme colors through Infima CSS variables (primary: `#4594d5`)
+- Dark mode via the `[data-theme="dark"]` selector; for components that must react to theme changes use `useTheme()` from `src/components/useTheme.ts`
+- The landing page's mock code cards are width-sensitive (`.codeCard` is a fixed 360px, and the editor mock's line numbers are a hardcoded 11 `<span>`s). Translated copy that is too long wraps and desyncs the gutter — see [agents/i18n.md](./agents/i18n.md).
+
+## Key dependencies
+
+**antd** (forms, buttons, cards, modals), **@iconify/react** (icons), **swiper** (carousel), **react-device-detect** (browser detection for the install guide).
+
+## Conventions index
+
+- [CONTRIBUTING.md](./CONTRIBUTING.md) — markdown/doc structure: file path is the URL, `title:` is the only page-title source, images in a sibling `.assets/` folder, the URL contract, translation glossary
+- [agents/i18n.md](./agents/i18n.md) — localization in code: locale detection, baseUrl, translated copy, cross-locale anchors, the single-source fallback mechanism, and a step-by-step checklist for adding a locale
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..43c994c2
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 519a3e4d..b7fb0dd1 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,8 +1,10 @@
 # 贡献指南 / Contributing Guide
 
-> EN summary: file path = doc ID = published URL, no `id:`/`sidebar_position:` frontmatter, no number-prefixed filenames, `title:` is the only page-title source (no body `# H1`), images live in a sibling `<doc-name>.assets/` folder, and every `docs/**/*.md` needs an `i18n/en/docusaurus-plugin-content-docs/current/**/*.md` mirror. Run `pnpm run check` before opening a PR — it enforces all of this. See [REFACTOR_PROPOSAL.md](./REFACTOR_PROPOSAL.md) for the full rationale.
+> EN summary: file path = doc ID = published URL, no `id:`/`sidebar_position:` frontmatter, no number-prefixed filenames, `title:` is the only page-title source (no body `# H1`), images live in a sibling `<doc-name>.assets/` folder, and every `docs/**/*.md` needs a mirror in each locale docs tree unless an explicit single-source fallback is configured. Run `pnpm run check` before opening a PR — it enforces all of this. For locale-aware code conventions see [agents/i18n.md](./agents/i18n.md).
 
-本文档记录本仓库的文档结构约定，帮助人类贡献者和 AI Agent 在不读遍全部历史讨论的情况下，正确地新增/修改文档。
+本文档记录本仓库的**文档结构**约定，帮助人类贡献者和 AI Agent 在不读遍全部历史讨论的情况下，正确地新增/修改文档。
+
+改动 `src/` 下的 React 代码或 `docusaurus.config.js` 之前，另见 [agents/i18n.md](./agents/i18n.md)——那里记录了多语言相关的代码约定（不要写死语言名、原生 `<a>` 要补 baseUrl、文案一律走 `<Translate>` 等），每条都对应一个真实踩过的坑。
 
 ## 核心约定
 
@@ -23,13 +25,13 @@
 2. frontmatter 只写 `title:`（必需）和可选的 `sidebar_label:`；不要写 `id:` 或 `sidebar_position:`。
 3. 正文**不要**再写一个 `# 标题` 作为 H1——`title:` 会自动渲染为页面标题。
 4. 在 `sidebars.js` 对应的数组里加一行 `"section/xxx"`（除非这是一个故意不出现在侧边栏的隐藏页面，如 `use/install_comple`）。
-5. 在 `i18n/en/docusaurus-plugin-content-docs/current/<section>/xxx.md` 创建英文镜像，路径和文件名必须完全一致。
-6. 图片放在 `docs/<section>/xxx.assets/` 下，用 `./xxx.assets/foo.png` 引用；纯 UI 截图等语言无关的图片，英文版可以用 `@site/docs/<section>/xxx.assets/foo.png` 直接复用中文版的图片，不必重复存一份二进制文件。
-7. 跑一次 `pnpm run build && pnpm run check`，确认三项检查全部通过。
+5. 在 `i18n/<locale>/docusaurus-plugin-content-docs/current/<section>/xxx.md` 为各非默认 locale 创建镜像，路径和文件名必须完全一致；`scripts/check-config.json` 中声明的单一来源 fallback 路径除外。
+6. 图片放在 `docs/<section>/xxx.assets/` 下，用 `./xxx.assets/foo.png` 引用；纯 UI 截图等语言无关的图片，英文版可以用 `@site/docs/<section>/xxx.assets/foo.png` 直接复用中文版的图片，不必重复存一份二进制文件。俄语版沿用英文截图，统一写 `@site/i18n/en/docusaurus-plugin-content-docs/current/<section>/xxx.assets/foo.png`——`i18n/ru/` 下不放任何图片二进制，避免同一张图在仓库里存三份。
+7. 跑一次 `pnpm run build && pnpm run check`，确认全部检查通过。
 
 ## 新增一条更新日志
 
-`change/` 下的版本文件（`v1.x.md`）不使用数字前缀排序；在 `sidebars.js` 的 `change` 数组里手动插入新版本号（数组顺序即侧边栏顺序，新版本插在最前面）。`change/beta-changelog.md` 是 Beta 版本的单独更新日志。
+`change/` 下的版本文件（`v1.x.md`）不使用数字前缀排序；在 `sidebars.js` 的 `change` 数组里手动插入新版本号（数组顺序即侧边栏顺序，新版本插在最前面）。`change/beta-changelog.md` 是 Beta 版本的单独更新日志。更新中文源文时仍需同步英文版本；俄语路由由 Docusaurus 直接回退到英文文档树，不要在 `i18n/ru/.../change/` 中恢复一份会漂移的副本。
 
 ## 加载不变的 URL（改动前必须确认不受影响）
 
@@ -43,22 +45,24 @@
 
 ## 翻译对照表
 
-| 中文 | English |
-|---|---|
-| 脚本猫 | ScriptCat |
-| 用户脚本 | user script |
-| 后台脚本 | background script |
-| 定时脚本 | scheduled script |
-| 油猴 | Tampermonkey |
+| 中文 | English | Русский |
+|---|---|---|
+| 脚本猫 | ScriptCat | ScriptCat |
+| 用户脚本 | user script | пользовательский скрипт |
+| 后台脚本 | background script | фоновый скрипт |
+| 定时脚本 | scheduled script | скрипт по расписанию |
+| 定时任务 | scheduled task | задача по расписанию |
+| 油猴 | Tampermonkey | Tampermonkey |
 
 英文标题结构应尽量与中文一一对应（标题层级、顺序一致），这样跨语言的锚点链接更容易对齐；注意 Docusaurus 生成的锚点是基于**渲染后的英文标题文本**，不是中文锚点的直接翻译（例如 `## Scheduled Script (\`@crontab\`)` 生成的锚点是 `#scheduled-script-crontab`，需要用构建产物核实，不要凭感觉猜。
 
 ## 本地检查命令
 
 ```bash
-pnpm run build          # 构建两个语言版本，onBrokenLinks/onBrokenAnchors 设置为 throw
-pnpm run check           # 依次跑 url 一致性 / i18n 覆盖率 / frontmatter 规范三项检查
+pnpm run build          # 构建 zh-Hans/en/ru，onBrokenLinks/onBrokenAnchors 设置为 throw
+pnpm run check           # 依次跑 URL / fallback 产物 / i18n 覆盖率 / frontmatter 检查
 pnpm run check:urls       # 单独跑 URL 不变契约检查
-pnpm run check:i18n       # 单独跑中英文档配对检查
+pnpm run check:fallbacks  # 单独检查 production build 中的 locale 单一来源 fallback
+pnpm run check:i18n       # 单独跑所有 locale 的文档配对及 fallback 例外检查
 pnpm run check:frontmatter # 单独跑 title/id/sidebar_position/H1 规范检查
 ```
diff --git a/agents/i18n.md b/agents/i18n.md
new file mode 100644
index 00000000..a1ebbc5b
--- /dev/null
+++ b/agents/i18n.md
@@ -0,0 +1,148 @@
+# 多语言（i18n）约定
+
+> EN summary: the site ships three locales (`zh-Hans` default with no URL prefix, `en`, `ru`). Never branch on a hardcoded locale name — read `i18n.currentLocale` / `i18n.locales` from `useDocusaurusContext()`. Plain `<a href="/...">` needs `withBaseUrl()`; `<Link to>` does not. All UI copy goes through `<Translate>` / `translate()`, and `i18n/en/code.json` must stay key-for-key identical to `i18n/ru/code.json`. Run `pnpm run build && pnpm run check` for all three locales before opening a PR.
+
+本文是 [AGENTS.md](../AGENTS.md) 「多语言」一节的展开；[CONTRIBUTING.md](../CONTRIBUTING.md) 管的是 markdown 文档的结构约定，本文管**代码和配置层面**的多语言约定。下面每一条都对应一个真实踩过的坑，改动 `src/`、`docusaurus.config.js` 或 `deploy/` 前请先扫一遍。
+
+站点的三个 locale：
+
+| locale | URL 前缀 | 文档来源 |
+|---|---|---|
+| `zh-Hans`（默认） | 无（`/`） | `docs/` |
+| `en` | `/en/` | `i18n/en/docusaurus-plugin-content-docs/current/` |
+| `ru` | `/ru/` | 同上的 `i18n/ru/...`，缺失时按 `scripts/check-config.json` 回退到 `en` |
+
+## 1. 不要假设只有两种语言
+
+这是本仓库最容易犯、也最容易漏检的错。以下写法都出现过：
+
+```tsx
+const zh = i18n.currentLocale !== "en";                       // ru 被判成中文
+const isEnglish = location.pathname.startsWith("/en/");        // /ru/ 被判成中文
+window.location.href = "/en/" + pathname.replace(/^\//, "");   // /ru/x 拼成 /en/ru/x（404）
+```
+
+规则：
+
+- 判断当前语言用 `useDocusaurusContext().i18n.currentLocale`，**不要解析 URL**。
+- 表达"非默认语言"写 `currentLocale !== defaultLocale`，不要枚举语言名。
+- 需要遍历语言时用 `i18n.locales`，标签和路径段取 `i18n.localeConfigs[locale]` 的 `.label` / `.path` / `.htmlLang`——这些都来自 `docusaurus.config.js`，以后加语言不用改代码。参考 `src/components/landing/LandingNav.tsx` 的 `LangSwitch`。
+- 要给路径换 locale 前缀，**必须先剥掉当前路径上已有的前缀**再拼新的，否则会拼出 `/en/ru/...`。参考 `src/theme/Root/index.tsx` 的 `splitLocale()` / `localePrefix()`。
+
+**这类假设不只藏在 `src/` 里**，还有两处按 locale 枚举、必须手工同步的地方：
+
+| 位置 | 内容 | 漏改的后果 |
+|---|---|---|
+| `docusaurus.config.js` 的 `metadataByLocale` | 每个 locale 的 SEO `keywords` / `description` | 回落到默认 locale，新语言页面挂着中文 meta |
+| `deploy/docker/nginx.conf` 的 `@handle_404` | 按 URL 前缀分流到各语言的 `404.html` | 该语言的 404 显示成中文页面（构建和 `check` 都发现不了，只有线上能看出来） |
+
+## 2. 原生 `<a href="/...">` 必须手动补 baseUrl
+
+非默认 locale 的 `siteConfig.baseUrl` 是 `/en/`、`/ru/`，不是 `/`。
+
+| 写法 | 是否自动带 baseUrl |
+|---|---|
+| `<Link to="/docs/x">`（`@docusaurus/Link`） | ✅ 首选 |
+| 原生 `<a href="/docs/x">` | ❌ |
+| antd `<Button href="/docs/x">` | ❌ |
+| markdown 里的 `[x](/docs/x)` | ✅（MDX 会渲染成 `Link`） |
+
+原生标签一律套 `withBaseUrl()`：
+
+```tsx
+import { useBaseUrlUtils } from "@docusaurus/useBaseUrl";
+const { withBaseUrl } = useBaseUrlUtils();
+<a href={withBaseUrl("/docs/use/use/")}>…</a>
+```
+
+`withBaseUrl` 对带协议的外链原样返回，也不会重复添加已有前缀，所以可以无脑套。踩过的地方：`src/theme/Footer/index.tsx`（**每一页都在**，影响最大）、`LandingNav`、`shared.tsx` 的 `usePrimaryInstall`、`pages/uninstall.tsx`。
+
+自查：`grep -rn 'href="/' src/ --include='*.tsx'` 应当只剩语言切换器里刻意写的站点根路径。
+
+## 3. UI 文案一律走 `<Translate>` / `translate()`
+
+- JSX 文本节点用 `<Translate id="...">中文默认值</Translate>`。
+- 需要拼进字符串或属性时用 `translate({ id, message })`。
+- 新 key 加到 `i18n/en/code.json` 和 `i18n/ru/code.json`；zh-Hans 直接用 JSX 里的内联默认值（`i18n/zh-Hans/code.json` 里没有 `home.*` 系列，这是正常的，不要补齐）。
+- **`i18n/en/code.json` 和 `i18n/ru/code.json` 必须键数一致、顺序一致**，方便逐行 diff 对照。key 按源码出现顺序排列，不是字母序。
+- 装饰性的示例代码块里的文案（`// @name 视频倍速控制`、`GM_notification('签到成功')`）也要翻译，但注意版式，见第 5 条。
+- 语言名本身不翻译：语言切换器里的"简体中文"在英文/俄文页面上仍是"简体中文"（并带 `lang="zh-Hans"`），这是惯例。
+
+自查（应当只剩注释和语言名）：
+
+```bash
+grep -rnP '[\x{4e00}-\x{9fff}]' src/ --include='*.tsx'
+```
+
+## 4. 外链里不要写死语言路径段
+
+`https://addons.mozilla.org/zh-CN/firefox/addon/scriptcat/` 会把英文/俄文用户送到中文商店页。去掉 `/zh-CN` 即可，商店会按浏览器语言自己跳。同理 Chrome / Edge 商店链接都不要带 `hl=` 之类的参数。
+
+已知例外：`src/theme/Footer/index.tsx` 里的 `https://scriptcat.org/zh-CN/`——脚本站是另一个站点，其多语言路径规则未确认，暂时保留。
+
+## 5. 译文长度会影响版式
+
+落地页的示例代码卡片对行宽敏感：
+
+- `.codeCard` 是**固定 360px** + `overflow: hidden`。
+- 编辑器 mock 的行号是写死的 11 个 `<span>`（`Array.from({ length: 11 })`），任何一行折行，行号就和代码错位。
+
+所以示例代码块里的译文，长度不要超过该代码块**原有最长行**。改完一定看构建产物，不要只看中文版。
+
+## 6. 跨语言复用的锚点要写显式 heading id
+
+Docusaurus 的锚点来自**渲染后的标题文本**，所以俄语标题会生成西里尔锚点，英文标题生成英文锚点，两者不通用。
+
+当一个页面被多个 locale 共用时（例如俄语 changelog 直接用英文文档树，其中的链接指向 `/use/use.md#load-unpacked-extension-installation`），就必须在**各语言**的目标标题上写显式 id：
+
+```markdown
+### Установка через загрузку распакованного расширения {#load-unpacked-extension-installation}
+```
+
+`onBrokenAnchors: "throw"` 会在构建时抓到不一致，但**必须三个 locale 都构建**才会暴露——所以别用 `--locale` 只构一个就下结论。
+
+## 7. 图片二进制只存一份
+
+见 [CONTRIBUTING.md](../CONTRIBUTING.md) 新增文档第 6 条：语言无关的截图用 `@site/docs/...` 复用中文版，俄语版统一引用英文树，`i18n/ru/` 下不放任何图片二进制。曾经有 21 张图（约 1 MB）在 ru 树里重复了一份。
+
+## 单一来源回退（fallback）机制
+
+`change/` 下的更新日志不做俄语翻译，而是让俄语路由直接编译英文文档树，避免翻译漂移。实现方式：`docusaurus.config.js` 根据 `DOCUSAURUS_CURRENT_LOCALE` 把 docs 插件的 `path` 指向 `i18n/en/.../current`，`i18n/ru/` 下存在的文件仍然会覆盖它。
+
+**注意**：这个 trick 的作用范围是**整棵树**——`i18n/ru/` 下缺任何一个文件都会静默回退到英文，而不只是 `change/`。`scripts/check-config.json` 里的 `i18nDocFallbacks.ru.paths` 只是给 `check:i18n` 用的白名单，Docusaurus 本身不认它。所以：
+
+- 漏译不会让构建失败，只会悄悄显示英文 → **必须依赖 `pnpm run check`**。
+- 新增有意的回退路径时，要同时改 `check-config.json` 和 `CONTRIBUTING.md`。
+- `check:fallbacks` 会在 `build/` 产物里核对这些页面的 edit 链接确实指向英文源，防止哪天配置失效而没人发现。
+
+## 新增一个 locale 的清单
+
+以 `xx` 代指新语言。**逐项走完，最后必须三个以上 locale 全量构建**。
+
+1. `docusaurus.config.js`：`i18n.locales` 加 `"xx"`，`i18n.localeConfigs.xx` 填 `label` / `direction` / `htmlLang`；`metadataByLocale` 加一组本地化的 `keywords` / `description`。
+2. `i18n/xx/code.json`：从 `i18n/en/code.json` 复制后逐条翻译，**保持键顺序一致**。
+3. `i18n/xx/docusaurus-theme-classic/navbar.json` / `footer.json`：翻译 `message` 字段（key 和 `description` 里的中文是 `write-translations` 生成的，保持原样）。
+4. `i18n/xx/docusaurus-plugin-content-docs/current.json`：翻译侧边栏分类名和 `version.label`。
+5. `i18n/xx/docusaurus-plugin-content-docs/current/`：镜像 `docs/` 下全部文档；要走单一来源回退的路径在 `scripts/check-config.json` 的 `i18nDocFallbacks` 里声明。图片不要复制二进制。
+6. `scripts/url-inventory.txt`：用 `node scripts/check-url-inventory.mjs --write` 更新，新增路由数应当等于每个 locale 的页面数。
+7. 检查代码里是否还有第 1、2 条描述的两语言假设——`Root` 的重定向和落地页语言切换器已经是配置驱动的，正常不需要改。
+8. `deploy/docker/nginx.conf`：`@handle_404` 的正则里加 `xx`，并加一个 `location = /xx/404.html`。**这一步没有任何检查脚本能兜住**，漏了就是线上该语言的 404 页变中文。
+9. **Algolia DocSearch 爬虫配置需要同步加上 `/xx/`**，见下节。
+10. `CONTRIBUTING.md` 的翻译对照表加一列。
+11. `pnpm run typecheck && pnpm run build && pnpm run check`，然后打开 `build/xx/` 抽查几页，确认 `<html lang>`、导航、页脚、语言切换器、图片、`404.html` 都对。
+
+## SEO 与搜索
+
+Docusaurus 自动处理的部分（不用手写）：`<html lang>`、`canonical`、`hreflang` 交叉引用（含 `x-default`）、`og:locale` / `og:locale:alternate`、`docsearch:language`、各 locale 独立的 `sitemap.xml`。
+
+需要人工处理的：
+
+- `metadataByLocale`（`docusaurus.config.js`）里的 `keywords` / `description` 要本地化，不能三种语言共用中文。
+- **Algolia DocSearch 的爬虫配置在 Algolia 后台，不在本仓库**。新增 locale 后如果不同步更新爬虫，该语言页面上的搜索框会返回空结果——`contextualSearch: true` 会按 `docsearch:language` 过滤，索引里没有对应语言的记录就什么都搜不到。
+
+## 已知例外与待办
+
+- **Algolia 爬虫尚未收录 `/ru/`**：俄语页面的搜索目前是空的，需要在 Algolia 后台补爬虫配置。
+- **本文的约定目前没有自动拦截**：`.gitea/workflows/ci.yaml` 会在每个 PR 上跑 `pnpm run typecheck && pnpm run build && pnpm run check`，所以文档配对、URL 契约、frontmatter、断链断锚点都是硬性把关的；但本文第 1～5 条（写死语言名、漏 `withBaseUrl`、硬编码中文、译文过宽）**没有对应的检查脚本**，只能靠 review 和自查命令。加检查脚本的话 CI 会自动生效。
+- **`src/components/HomepageFeatures/` 是死代码**：首页改版后已无任何地方 import，内含约 30 行硬编码中文。建议直接删除，不要花时间翻译它。
+- **`LINKS.search()` 的关键词有意保留中文**（`src/components/landing/shared.tsx`）：场景卡片的标题是翻译过的，但跳转到脚本站的搜索关键词仍是"去广告""购物"等中文。脚本站内容以中文为主，换成外语关键词很可能搜出 0 条结果，属于有意为之。若确认脚本站支持多语言搜索再改。
diff --git a/deploy/docker/nginx.conf b/deploy/docker/nginx.conf
index c0dcad61..bb62b634 100644
--- a/deploy/docker/nginx.conf
+++ b/deploy/docker/nginx.conf
@@ -9,25 +9,35 @@ server {
     
     # 处理404页面的逻辑
     location @handle_404 {
-        # 检查是否为英文版本（以/en/开头）
+        # 带语言前缀的路径返回该语言的404页面。
+        # 默认 locale（zh-Hans）没有 URL 前缀，落到最后的中文404。
+        # 新增 locale 时必须在这里加一行、并在下面加一个 location，
+        # 否则该语言的404会显示成中文页面。见 agents/i18n.md 的新增 locale 清单。
         if ($uri ~ ^/en/) {
             return 302 /en/404.html;
         }
+        if ($uri ~ ^/ru/) {
+            return 302 /ru/404.html;
+        }
         # 默认返回中文404页面
         return 302 /404.html;
     }
-    
+
     # 确保404.html能够正常访问
     location = /404.html {
         # 移除 internal 指令，允许直接访问404页面
         try_files $uri =404;
     }
-    
-    # 确保英文版404.html能够正常访问
+
+    # 确保各语言版404.html能够正常访问（否则上面的302会再次触发error_page）
     location = /en/404.html {
         try_files $uri =404;
     }
 
+    location = /ru/404.html {
+        try_files $uri =404;
+    }
+
     # 尝试文件，如果不存在则显示404页面
     location / {
         try_files $uri $uri/index.html $uri/ /404.html;
diff --git a/docusaurus.config.js b/docusaurus.config.js
index e1fa33ff..373d037c 100644
--- a/docusaurus.config.js
+++ b/docusaurus.config.js
@@ -3,6 +3,35 @@
 
 import { themes as prismThemes } from "prism-react-renderer";
 
+const { defaultLocale, i18nDocFallbacks = {} } = require("./scripts/check-config.json");
+const currentLocale = process.env.DOCUSAURUS_CURRENT_LOCALE ?? defaultLocale;
+const docsFallbackLocale = i18nDocFallbacks[currentLocale]?.sourceLocale;
+const docsPath = docsFallbackLocale
+  ? `i18n/${docsFallbackLocale}/docusaurus-plugin-content-docs/current`
+  : "docs";
+
+const metadataByLocale = {
+  "zh-Hans": {
+    keywords:
+      "scriptcat,userscript,browser extension,浏览器扩展,用户脚本,后台脚本,脚本猫,tampermonkey,violentmonkey,greasemonkey,javascript,自动化脚本,网页增强",
+    description:
+      "ScriptCat 是一个可以执行自定义脚本的浏览器扩展，支持用户脚本、后台脚本等多种脚本类型。提供强大的脚本管理、同步、订阅等功能。",
+  },
+  en: {
+    keywords:
+      "scriptcat,userscript,browser extension,user scripts,background scripts,scheduled scripts,userscript manager,tampermonkey,violentmonkey,greasemonkey,javascript,browser automation",
+    description:
+      "ScriptCat is an open-source browser extension for user scripts, background scripts, and scheduled scripts, with powerful management, sync, and subscription features.",
+  },
+  ru: {
+    keywords:
+      "scriptcat,userscript,расширение браузера,пользовательские скрипты,фоновые скрипты,скрипты по расписанию,менеджер пользовательских скриптов,tampermonkey,violentmonkey,greasemonkey,javascript,автоматизация браузера",
+    description:
+      "ScriptCat — открытое расширение браузера для пользовательских, фоновых скриптов и скриптов по расписанию с удобным управлением, синхронизацией и подписками.",
+  },
+};
+const metadata = metadataByLocale[currentLocale] ?? metadataByLocale[defaultLocale];
+
 /** @type {import('@docusaurus/types').Config} */
 const config = {
   title: "ScriptCat",
@@ -47,8 +76,8 @@ const config = {
   // metadata like html lang. For example, if your site is Chinese, you may want
   // to replace "en" with "zh-Hans".
   i18n: {
-    defaultLocale: "zh-Hans",
-    locales: ["zh-Hans", "en"],
+    defaultLocale,
+    locales: ["zh-Hans", "en", "ru"],
     localeConfigs: {
       "zh-Hans": {
         label: "简体中文",
@@ -60,6 +89,11 @@ const config = {
         direction: "ltr",
         htmlLang: "en",
       },
+      ru: {
+        label: "Русский",
+        direction: "ltr",
+        htmlLang: "ru",
+      },
     },
   },
 
@@ -69,6 +103,11 @@ const config = {
       /** @type {import('@docusaurus/preset-classic').Options} */
       ({
         docs: {
+          // Docusaurus normally falls back to the default (Chinese) docs tree.
+          // For configured locales, use another locale as the base tree while
+          // still letting localized files override it. check:i18n restricts
+          // which paths may rely on this fallback.
+          path: docsPath,
           sidebarPath: require.resolve("./sidebars.js"),
           // Please change this to your repo.
           // Remove this to remove the "edit this page" links.
@@ -100,13 +139,11 @@ const config = {
       metadata: [
         {
           name: "keywords",
-          content:
-            "scriptcat,userscript,browser extension,浏览器扩展,用户脚本,后台脚本,脚本猫,tampermonkey,violentmonkey,greasemonkey,javascript,自动化脚本,网页增强",
+          content: metadata.keywords,
         },
         {
           name: "description",
-          content:
-            "ScriptCat 是一个可以执行自定义脚本的浏览器扩展，支持用户脚本、后台脚本等多种脚本类型。提供强大的脚本管理、同步、订阅等功能。",
+          content: metadata.description,
         },
       ],
       navbar: {
diff --git a/i18n/en/code.json b/i18n/en/code.json
index e4ddca0b..375c5149 100644
--- a/i18n/en/code.json
+++ b/i18n/en/code.json
@@ -27,6 +27,10 @@
     "message": "Find these updates useful? Star us on GitHub to support our work",
     "description": "GitHub star bar subtitle on changelog page"
   },
+  "homepage.meta.keywords": {
+    "message": "ScriptCat,user scripts,browser extension,userscript,Tampermonkey,Violentmonkey,background scripts,scheduled scripts,browser automation,ad blocker,script store",
+    "description": "Homepage SEO keywords"
+  },
   "homepage.meta.title": {
     "message": "ScriptCat - Powerful Browser Script Engine",
     "description": "Homepage meta title for SEO"
@@ -503,6 +507,18 @@
     "message": "If you change your mind, you can always reinstall:",
     "description": "Reinstall message"
   },
+  "uninstall.reinstall.chrome": {
+    "message": "Chrome Web Store",
+    "description": "Reinstall from Chrome Web Store button"
+  },
+  "uninstall.reinstall.edge": {
+    "message": "Edge Add-ons",
+    "description": "Reinstall from Edge Add-ons button"
+  },
+  "uninstall.reinstall.firefox": {
+    "message": "Firefox Add-ons",
+    "description": "Reinstall from Firefox Add-ons button"
+  },
   "uninstall.thanks.considerReinstall": {
     "message": "If you change your mind, you're always welcome back",
     "description": "Consider reinstall message"
@@ -858,6 +874,14 @@
   "home.dev.run": {
     "message": "Run"
   },
+  "home.dev.mock.name": {
+    "message": "Daily check-in",
+    "description": "@name value in the editor mock code block"
+  },
+  "home.dev.mock.toast": {
+    "message": "Checked in",
+    "description": "Notification text in the editor mock code block"
+  },
   "home.comm.eyebrow": {
     "message": "Open source · OPEN SOURCE"
   },
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/change/index.md b/i18n/en/docusaurus-plugin-content-docs/current/change/index.md
index ce3ef839..f0e5196d 100644
--- a/i18n/en/docusaurus-plugin-content-docs/current/change/index.md
+++ b/i18n/en/docusaurus-plugin-content-docs/current/change/index.md
@@ -12,7 +12,7 @@ import SponsorBlock from '@site/src/components/SponsorBlock/en.mdx';
 
 For Beta version changelog, please see [Beta Changelog](./beta-changelog.md)
 
-⚠️ Please note that if you are using Windows 8/7/XP, or your browser kernel version is lower than 120, you need to manually install the [legacy version of ScriptCat](https://github.com/scriptscat/scriptcat/releases). v0.16.x is the last version that supports Manifest V2. Installation steps can be found at: [Install Extension by Loading Unpacked](/docs/use/use/#load-unpacked-extension-installation).
+⚠️ Please note that if you are using Windows 8/7/XP, or your browser kernel version is lower than 120, you need to manually install the [legacy version of ScriptCat](https://github.com/scriptscat/scriptcat/releases). v0.16.x is the last version that supports Manifest V2. Installation steps can be found at: [Install Extension by Loading Unpacked](/use/use.md#load-unpacked-extension-installation).
 
 <a name="1.4.0"></a>
 
diff --git a/i18n/ru/code.json b/i18n/ru/code.json
new file mode 100644
index 00000000..3d948b60
--- /dev/null
+++ b/i18n/ru/code.json
@@ -0,0 +1,951 @@
+{
+  "githubStar.button.label": {
+    "message": "Star",
+    "description": "GitHub star button label"
+  },
+  "githubStar.home.title": {
+    "message": "ScriptCat — бесплатный и с открытым исходным кодом",
+    "description": "GitHub star bar title on homepage"
+  },
+  "githubStar.home.subtitle": {
+    "message": "Поставьте Star, если проект полезен — это нас мотивирует",
+    "description": "GitHub star bar subtitle on homepage"
+  },
+  "githubStar.install.title": {
+    "message": "Нравится ScriptCat?",
+    "description": "GitHub star bar title on install-complete page"
+  },
+  "githubStar.install.subtitle": {
+    "message": "Поставьте Star на GitHub — так больше людей узнают о проекте 🌟",
+    "description": "GitHub star bar subtitle on install-complete page"
+  },
+  "githubStar.changelog.title": {
+    "message": "ScriptCat становится всё лучше 🚀",
+    "description": "GitHub star bar title on changelog page"
+  },
+  "githubStar.changelog.subtitle": {
+    "message": "Обновления полезны? Поддержите нас Star на GitHub",
+    "description": "GitHub star bar subtitle on changelog page"
+  },
+  "homepage.meta.keywords": {
+    "message": "ScriptCat,пользовательские скрипты,расширение браузера,userscript,Tampermonkey,Violentmonkey,фоновые скрипты,скрипты по расписанию,автоматизация браузера,блокировка рекламы,магазин скриптов",
+    "description": "Homepage SEO keywords"
+  },
+  "homepage.meta.title": {
+    "message": "ScriptCat — мощный движок пользовательских скриптов",
+    "description": "Homepage meta title for SEO"
+  },
+  "homepage.meta.description": {
+    "message": "ScriptCat — мощный открытый движок браузерных скриптов: настраивайте веб-страницы, блокируйте рекламу, автоматизируйте задачи и улучшайте просмотр. Совместим с Tampermonkey и предлагает больше возможностей.",
+    "description": "Homepage meta description for SEO"
+  },
+  "homepage.og.title": {
+    "message": "ScriptCat — мощный движок браузерных скриптов",
+    "description": "Open Graph title for social sharing"
+  },
+  "homepage.og.description": {
+    "message": "Открытый движок браузерных скриптов, который расширяет возможности браузера. Пользовательские и фоновые скрипты, совместимость с Tampermonkey, расширенный функционал.",
+    "description": "Open Graph description for social sharing"
+  },
+  "homepage.twitter.title": {
+    "message": "ScriptCat — мощный движок браузерных скриптов",
+    "description": "Twitter card title"
+  },
+  "homepage.twitter.description": {
+    "message": "Открытый движок браузерных скриптов, который делает больше",
+    "description": "Twitter card description"
+  },
+  "homepage.hero.title": {
+    "message": "Лучший движок скриптов для",
+    "description": "Main title on the homepage hero section"
+  },
+  "homepage.hero.title.engine": {
+    "message": "улучшенного браузера",
+    "description": "Gradient text in main title"
+  },
+  "homepage.hero.subtitle.userScript": {
+    "message": "пользовательских скриптов",
+    "description": "User script highlight"
+  },
+  "homepage.hero.subtitle.possibilities": {
+    "message": ", открывая безграничные возможности браузера!",
+    "description": "Browser possibilities text"
+  },
+  "homepage.hero.subtitle.main": {
+    "message": "ScriptCat — мощный открытый движок браузерных скриптов: легко настраивайте сайты, убирайте рекламу, автоматизируйте задачи и улучшайте веб-серфинг. Совместим с Tampermonkey и даёт дополнительные возможности и оптимизации.",
+    "description": "Main subtitle description on homepage"
+  },
+  "homepage.hero.subtitle.highlight": {
+    "message": "Расширение браузера для выполнения",
+    "description": "Highlighted subtitle on homepage"
+  },
+  "homepage.hero.button.browseScripts": {
+    "message": "Смотреть библиотеку скриптов",
+    "description": "Button text for browsing scripts"
+  },
+  "homepage.hero.browser.edge": {
+    "message": "Добавить в Edge",
+    "description": "Button text for Edge browser"
+  },
+  "homepage.hero.browser.chrome": {
+    "message": "Добавить в Chrome",
+    "description": "Button text for Chrome browser"
+  },
+  "homepage.hero.browser.firefox": {
+    "message": "Добавить в Firefox",
+    "description": "Button text for Firefox browser"
+  },
+  "homepage.hero.browser.default": {
+    "message": "Установить расширение",
+    "description": "Default button text for browser installation"
+  },
+  "homepage.hero.browser.crx": {
+    "message": "Скачать пакет для ручной установки",
+    "description": "Button text for manual installation"
+  },
+  "homepage.hero.trustBadges.title": {
+    "message": "Доверие и поддержка технического сообщества",
+    "description": "Trust badges section title"
+  },
+  "homepage.features.title.powerful": {
+    "message": "Мощные возможности, ",
+    "description": "Features section title part 1"
+  },
+  "homepage.features.title.possibilities": {
+    "message": "безграничный потенциал",
+    "description": "Features section title highlight"
+  },
+  "homepage.features.subtitle": {
+    "message": "ScriptCat предлагает набор мощных функций, чтобы легко расширять возможности браузера и создавать свой веб-опыт.",
+    "description": "Features section subtitle"
+  },
+  "homepage.features.tampermonkey.title": {
+    "message": "Совместимость с Tampermonkey",
+    "description": "Feature title: Tampermonkey compatibility"
+  },
+  "homepage.features.tampermonkey.description": {
+    "message": "Полная совместимость с форматом скриптов Tampermonkey: бесшовная миграция существующей библиотеки без затрат на переход.",
+    "description": "Feature description: Tampermonkey compatibility"
+  },
+  "homepage.features.background.title": {
+    "message": "Фоновые скрипты",
+    "description": "Feature title: Background scripts"
+  },
+  "homepage.features.background.description": {
+    "message": "В отличие от обычных пользовательских скриптов, позволяют работать в фоне без открытых вкладок.",
+    "description": "Feature description: Background scripts"
+  },
+  "homepage.features.security.title": {
+    "message": "Безопасность и надёжность",
+    "description": "Feature title: Security"
+  },
+  "homepage.features.security.description": {
+    "message": "Строгий контроль разрешений, прозрачное поведение скриптов — защита от вредоносного кода и вашей конфиденциальности.",
+    "description": "Feature description: Security"
+  },
+  "homepage.features.editor.title": {
+    "message": "Встроенный редактор кода",
+    "description": "Feature title: Code editor"
+  },
+  "homepage.features.editor.description": {
+    "message": "Мощный редактор с подсветкой синтаксиса, автодополнением и подсказками об ошибках — писать скрипты удобнее.",
+    "description": "Feature description: Code editor"
+  },
+  "homepage.features.api.title": {
+    "message": "Мощные API",
+    "description": "Feature title: APIs"
+  },
+  "homepage.features.api.description": {
+    "message": "Богаче, чем GM: файловое хранилище, пользовательские настройки и другие расширенные возможности.",
+    "description": "Feature description: APIs"
+  },
+  "homepage.features.store.title": {
+    "message": "Магазин скриптов",
+    "description": "Feature title: Script store"
+  },
+  "homepage.features.store.description": {
+    "message": "Устанавливайте популярные скрипты в один клик или публикуйте свои работы для сообщества — живая экосистема.",
+    "description": "Feature description: Script store"
+  },
+  "homepage.comparison.title.why": {
+    "message": "Почему выбирают",
+    "description": "Comparison section title part 1"
+  },
+  "homepage.comparison.subtitle": {
+    "message": "По сравнению с другими движками скриптов ScriptCat даёт больше преимуществ и расширенных функций",
+    "description": "Comparison section subtitle"
+  },
+  "homepage.comparison.feature": {
+    "message": "Функция",
+    "description": "Comparison table header: Feature"
+  },
+  "homepage.comparison.feature.compatibility": {
+    "message": "Совместимость скриптов",
+    "description": "Comparison feature: Script compatibility"
+  },
+  "homepage.comparison.feature.background": {
+    "message": "Фоновые скрипты",
+    "description": "Comparison feature: Background scripts"
+  },
+  "homepage.comparison.feature.opensource": {
+    "message": "Бесплатный open source",
+    "description": "Comparison feature: Open source"
+  },
+  "homepage.comparison.feature.mv3": {
+    "message": "Поддержка MV3",
+    "description": "Comparison feature: MV3 Support"
+  },
+  "homepage.comparison.feature.sync": {
+    "message": "Облачная синхронизация",
+    "description": "Comparison feature: Cloud sync"
+  },
+  "homepage.comparison.feature.api": {
+    "message": "Мощные API",
+    "description": "Comparison feature: Powerful APIs"
+  },
+  "homepage.comparison.feature.community": {
+    "message": "Поддержка сообщества",
+    "description": "Comparison feature: Community support"
+  },
+  "homepage.comparison.label.efficient": {
+    "message": "Эффективно",
+    "description": "Comparison label: Efficient"
+  },
+  "homepage.comparison.label.multiplatform": {
+    "message": "Кроссплатформенно",
+    "description": "Comparison label: Multi-platform"
+  },
+  "homepage.scenario.title.solve": {
+    "message": "Скрипты, которые решают ",
+    "description": "Scenario section title part 1"
+  },
+  "homepage.scenario.title.problems": {
+    "message": "реальные задачи",
+    "description": "Scenario section title highlight"
+  },
+  "homepage.scenario.title.scripts": {
+    "message": "",
+    "description": "Scenario section title part 2"
+  },
+  "homepage.scenario.subtitle": {
+    "message": "Посмотрите, как ScriptCat меняет опыт веб-сёрфинга",
+    "description": "Scenario section subtitle"
+  },
+  "homepage.scenario.video.title": {
+    "message": "Улучшение видеосайтов",
+    "description": "Video scenario title"
+  },
+  "homepage.scenario.video.subtitle": {
+    "message": "Оптимизируйте просмотр видео",
+    "description": "Video scenario subtitle"
+  },
+  "homepage.scenario.video.tag": {
+    "message": "Популярные сценарии",
+    "description": "Video scenario tag"
+  },
+  "homepage.scenario.video.feature.speed": {
+    "message": "Управление скоростью видео",
+    "description": "Video feature: Speed control"
+  },
+  "homepage.scenario.video.feature.download": {
+    "message": "Скачивание видео в один клик",
+    "description": "Video feature: Download"
+  },
+  "homepage.scenario.video.feature.adblock": {
+    "message": "Автопропуск рекламы",
+    "description": "Video feature: Ad blocking"
+  },
+  "homepage.scenario.video.feature.ui": {
+    "message": "Упрощение интерфейса",
+    "description": "Video feature: UI optimization"
+  },
+  "homepage.scenario.video.sites": {
+    "message": "Поддерживаемые сайты",
+    "description": "Video scenario supported sites label"
+  },
+  "homepage.scenario.video.getScript": {
+    "message": "Получить скрипт →",
+    "description": "Video scenario get script link"
+  },
+  "homepage.scenario.shopping.title": {
+    "message": "Помощник покупок",
+    "description": "Shopping scenario title"
+  },
+  "homepage.scenario.shopping.subtitle": {
+    "message": "Делает покупки проще",
+    "description": "Shopping scenario subtitle"
+  },
+  "homepage.scenario.shopping.tag": {
+    "message": "Практичные инструменты",
+    "description": "Shopping scenario tag"
+  },
+  "homepage.scenario.shopping.feature.history": {
+    "message": "История цен",
+    "description": "Shopping feature: Price history"
+  },
+  "homepage.scenario.shopping.feature.coupon": {
+    "message": "Автопоиск купонов",
+    "description": "Shopping feature: Coupon search"
+  },
+  "homepage.scenario.shopping.feature.compare": {
+    "message": "Сравнение цен",
+    "description": "Shopping feature: Price comparison"
+  },
+  "homepage.scenario.shopping.feature.alert": {
+    "message": "Уведомления о снижении цены",
+    "description": "Shopping feature: Price alert"
+  },
+  "homepage.scenario.sites.more": {
+    "message": "+Ещё",
+    "description": "More sites indicator in scenario cards"
+  },
+  "homepage.download.title.ready": {
+    "message": "Готовы",
+    "description": "Download section title part 1"
+  },
+  "homepage.download.title.enhance": {
+    "message": "улучшить просмотр в браузере",
+    "description": "Download section title highlight"
+  },
+  "homepage.download.title.question": {
+    "message": "?",
+    "description": "Download section title part 2"
+  },
+  "homepage.download.subtitle": {
+    "message": "Установите ScriptCat и откройте безграничные возможности веба",
+    "description": "Download section subtitle"
+  },
+  "homepage.download.edge": {
+    "message": "Магазин расширений Edge",
+    "description": "Download button: Edge store"
+  },
+  "homepage.download.chrome": {
+    "message": "Магазин расширений Chrome",
+    "description": "Download button: Chrome store"
+  },
+  "homepage.download.firefox": {
+    "message": "Магазин расширений Firefox",
+    "description": "Download button: Firefox store"
+  },
+  "homepage.download.github": {
+    "message": "Скачать с GitHub",
+    "description": "Download button: GitHub"
+  },
+  "homepage.download.popup.title": {
+    "message": "ScriptCat включён",
+    "description": "Extension popup title"
+  },
+  "homepage.download.popup.text": {
+    "message": "На этой странице работают 3 скрипта",
+    "description": "Extension popup text"
+  },
+  "homepage.footer.contributors.title": {
+    "message": "Спасибо всем участникам",
+    "description": "Footer contributors section title"
+  },
+  "footer.description": {
+    "message": "Мощный движок браузерных скриптов, который делает веб богаче и интереснее.",
+    "description": "Footer description"
+  },
+  "footer.product.title": {
+    "message": "Продукт",
+    "description": "Footer product section title"
+  },
+  "footer.product.features": {
+    "message": "Возможности",
+    "description": "Footer product features link"
+  },
+  "footer.product.scriptStore": {
+    "message": "Магазин скриптов",
+    "description": "Footer product script store link"
+  },
+  "footer.product.changelog": {
+    "message": "История изменений",
+    "description": "Footer product changelog link"
+  },
+  "footer.resources.title": {
+    "message": "Ресурсы",
+    "description": "Footer resources section title"
+  },
+  "footer.resources.devDocs": {
+    "message": "Документация разработчика",
+    "description": "Footer resources development docs link"
+  },
+  "footer.resources.apiReference": {
+    "message": "Справочник API",
+    "description": "Footer resources API reference link"
+  },
+  "footer.resources.examples": {
+    "message": "Примеры скриптов",
+    "description": "Footer resources example scripts link"
+  },
+  "footer.resources.faq": {
+    "message": "FAQ",
+    "description": "Footer resources FAQ link"
+  },
+  "footer.community.title": {
+    "message": "Сообщество",
+    "description": "Footer community section title"
+  },
+  "footer.community.forum": {
+    "message": "Форум",
+    "description": "Footer community forum link"
+  },
+  "footer.community.discord": {
+    "message": "Канал Discord",
+    "description": "Footer community Discord link"
+  },
+  "footer.community.contributing": {
+    "message": "Как внести вклад",
+    "description": "Footer community contributing guide link"
+  },
+  "footer.community.issues": {
+    "message": "Сообщить о проблеме",
+    "description": "Footer community report issues link"
+  },
+  "footer.community.contact": {
+    "message": "Связаться с командой",
+    "description": "Footer community contact team link"
+  },
+  "footer.copyright.allRightsReserved": {
+    "message": "Все права защищены.",
+    "description": "Footer copyright all rights reserved text"
+  },
+  "footer.copyright.privacy": {
+    "message": "Политика конфиденциальности",
+    "description": "Footer copyright privacy policy link"
+  },
+  "footer.copyright.terms": {
+    "message": "Условия использования",
+    "description": "Footer copyright terms of use link"
+  },
+  "footer.copyright.license": {
+    "message": "Лицензионное соглашение",
+    "description": "Footer copyright license link"
+  },
+  "uninstall.title": {
+    "message": "Опрос при удалении",
+    "description": "Title of the uninstall survey page"
+  },
+  "uninstall.description": {
+    "message": "Спасибо, что пользовались ScriptCat. Расскажите, почему вы удаляете расширение.",
+    "description": "Description of the uninstall survey page"
+  },
+  "uninstall.header.title": {
+    "message": "Жаль, что вы удаляете ScriptCat",
+    "description": "Main header title on uninstall survey page"
+  },
+  "uninstall.header.subtitle": {
+    "message": "Если несложно, поделитесь мнением — это поможет нам становиться лучше",
+    "description": "Subtitle on uninstall survey page"
+  },
+  "uninstall.question.reason": {
+    "message": "Какова основная причина удаления ScriptCat?",
+    "description": "Question about uninstall reason"
+  },
+  "uninstall.question.feedback": {
+    "message": "Можете ли вы подробнее описать ситуацию?",
+    "description": "Question about detailed feedback"
+  },
+  "uninstall.reason.bugs": {
+    "message": "Ошибки или сбои",
+    "description": "Uninstall reason: bugs"
+  },
+  "uninstall.reason.no_need": {
+    "message": "ScriptCat больше не нужен",
+    "description": "Uninstall reason: no longer need"
+  },
+  "uninstall.reason.features": {
+    "message": "Нет нужных мне функций",
+    "description": "Uninstall reason: missing features"
+  },
+  "uninstall.reason.alternative": {
+    "message": "Нашёл(ла) лучшую альтернативу",
+    "description": "Uninstall reason: found alternative"
+  },
+  "uninstall.reason.other": {
+    "message": "Другие причины",
+    "description": "Uninstall reason: other"
+  },
+  "uninstall.feedback.placeholder": {
+    "message": "Опишите конкретные проблемы, предложения или другие мысли...",
+    "description": "Placeholder text for feedback textarea"
+  },
+  "uninstall.button.submit": {
+    "message": "Отправить отзыв",
+    "description": "Submit button text"
+  },
+  "uninstall.warning.selectReason": {
+    "message": "Выберите причину удаления",
+    "description": "Warning when no reason is selected"
+  },
+  "uninstall.success.submitted": {
+    "message": "Спасибо за отзыв!",
+    "description": "Success message after submission"
+  },
+  "uninstall.error.submit": {
+    "message": "Не удалось отправить, попробуйте позже",
+    "description": "Error message when submission fails"
+  },
+  "uninstall.thanks.title": {
+    "message": "Спасибо за отзыв!",
+    "description": "Thank you page title"
+  },
+  "uninstall.thanks.message": {
+    "message": "Ваше мнение очень важно и поможет улучшить ScriptCat.",
+    "description": "Thank you page message"
+  },
+  "uninstall.thanks.backHome": {
+    "message": "На главную",
+    "description": "Back to home button"
+  },
+  "uninstall.thanks.reportIssue": {
+    "message": "Сообщить о проблеме",
+    "description": "Report issue button"
+  },
+  "uninstall.reinstall.message": {
+    "message": "Если передумаете, всегда можно установить снова:",
+    "description": "Reinstall message"
+  },
+  "uninstall.reinstall.chrome": {
+    "message": "Интернет-магазин Chrome",
+    "description": "Reinstall from Chrome Web Store button"
+  },
+  "uninstall.reinstall.edge": {
+    "message": "Дополнения Edge",
+    "description": "Reinstall from Edge Add-ons button"
+  },
+  "uninstall.reinstall.firefox": {
+    "message": "Дополнения Firefox",
+    "description": "Reinstall from Firefox Add-ons button"
+  },
+  "uninstall.thanks.considerReinstall": {
+    "message": "Если передумаете — мы всегда рады видеть вас снова",
+    "description": "Consider reinstall message"
+  },
+  "uninstall.thanks.submitAnother": {
+    "message": "Отправить другой отзыв",
+    "description": "Submit another feedback button"
+  },
+  "uninstall.sidebar.reinstall.title": {
+    "message": "Мы всегда рады видеть вас снова",
+    "description": "Sidebar reinstall title"
+  },
+  "uninstall.sidebar.help.title": {
+    "message": "Нужна помощь?",
+    "description": "Sidebar help title"
+  },
+  "uninstall.sidebar.help.description": {
+    "message": "Возникли трудности? Мы поможем разобраться",
+    "description": "Sidebar help description"
+  },
+  "uninstall.sidebar.help.github": {
+    "message": "GitHub Issues",
+    "description": "GitHub issues button"
+  },
+  "uninstall.sidebar.help.docs": {
+    "message": "Документация",
+    "description": "View docs button"
+  },
+  "uninstall.bug.alert.title": {
+    "message": "Нашли ошибку?",
+    "description": "Bug alert title"
+  },
+  "uninstall.bug.alert.description": {
+    "message": "Если вы столкнулись с ошибкой или сбоем, рекомендуем сразу создать issue на GitHub — так обратная связь и поддержка будут быстрее.",
+    "description": "Bug alert description"
+  },
+  "uninstall.bug.alert.button": {
+    "message": "Сообщить о проблеме на GitHub",
+    "description": "Bug alert button text"
+  },
+  "uninstall.feature.alert.title": {
+    "message": "Не хватает функции?",
+    "description": "Feature alert title"
+  },
+  "uninstall.feature.alert.description": {
+    "message": "Мы ценим запросы на функции! Опишите желаемое подробно на GitHub — так мы лучше поймём потребности и приоритизируем реализацию.",
+    "description": "Feature alert description"
+  },
+  "uninstall.feature.alert.button": {
+    "message": "Предложить функцию на GitHub",
+    "description": "Feature alert button text"
+  },
+  "home.install.edge": {
+    "message": "Добавить в Edge"
+  },
+  "home.install.chrome": {
+    "message": "Добавить в Chrome"
+  },
+  "home.install.firefox": {
+    "message": "Добавить в Firefox"
+  },
+  "home.install.manual": {
+    "message": "Скачать пакет и установить вручную"
+  },
+  "home.install.guide": {
+    "message": "Инструкция по установке"
+  },
+  "home.hero.installTo": {
+    "message": "Добавить в {browser}"
+  },
+  "home.hero.moreBrowsers": {
+    "message": "Другие браузеры"
+  },
+  "home.hero.eyebrow": {
+    "message": "Открытый движок userscript · совместим с Tampermonkey"
+  },
+  "home.hero.title1": {
+    "message": "Дайте браузеру"
+  },
+  "home.hero.title2": {
+    "message": ""
+  },
+  "home.hero.title3": {
+    "message": "суперспособности"
+  },
+  "home.hero.subhead": {
+    "message": "Блокируйте рекламу, улучшайте видео, автоматизируйте рутину — устанавливайте скрипты сообщества из магазина в один клик; для разработчиков — фоновые скрипты и мощные API. Совместим с Tampermonkey: существующие скрипты переносятся без затрат."
+  },
+  "home.hero.browse": {
+    "message": "Смотреть скрипты"
+  },
+  "home.hero.trust": {
+    "message": "Работает в Chrome · Edge · Firefox — полностью бесплатно и open source"
+  },
+  "home.hero.mock.speed": {
+    "message": "Управление скоростью видео"
+  },
+  "home.hero.mock.adblock": {
+    "message": "Автопропуск рекламы"
+  },
+  "home.hero.mock.dark": {
+    "message": "Тёмная тема для страниц"
+  },
+  "home.hero.mock.skip": {
+    "message": "Пропуск рекламы"
+  },
+  "home.hero.mock.running": {
+    "message": "На этой странице работают 3 скрипта"
+  },
+  "home.hero.mock.add": {
+    "message": "Добавить из магазина скриптов"
+  },
+  "home.hero.chip.installed": {
+    "message": "Скрипт установлен"
+  },
+  "home.hero.chip.installedSub": {
+    "message": "Video Enhancer v2.1"
+  },
+  "home.hero.chip.background": {
+    "message": "3 скрипта работают в фоне"
+  },
+  "home.trust.eyebrow": {
+    "message": "ДОВЕРИЕ ПОЛЬЗОВАТЕЛЕЙ И РАЗРАБОТЧИКОВ ПО ВСЕМУ МИРУ"
+  },
+  "home.trust.users": {
+    "message": "Установок"
+  },
+  "home.trust.scripts": {
+    "message": "Скриптов сообщества"
+  },
+  "home.trust.stars": {
+    "message": "GitHub Stars"
+  },
+  "home.trust.contributors": {
+    "message": "Участников"
+  },
+  "home.sc.eyebrow": {
+    "message": "Для всех · Код не нужен"
+  },
+  "home.sc.title1": {
+    "message": "Без кода — только "
+  },
+  "home.sc.title2": {
+    "message": "один клик"
+  },
+  "home.sc.title3": {
+    "message": ", чтобы решить повседневные раздражители"
+  },
+  "home.sc.sub": {
+    "message": "Возьмите скрипт из магазина — реклама, видео, покупки, продуктивность: всё сделано за вас."
+  },
+  "home.sc.featured.tag": {
+    "message": "Самое популярное"
+  },
+  "home.sc.featured.t": {
+    "message": "Видео — полностью улучшено"
+  },
+  "home.sc.featured.d": {
+    "message": "Скорость, автопропуск рекламы, скачивание в один клик, картинка в картинке — удобнее Bilibili / YouTube / Netflix."
+  },
+  "home.sc.featured.c1": {
+    "message": "Скорость"
+  },
+  "home.sc.featured.c2": {
+    "message": "Блокировка рекламы"
+  },
+  "home.sc.featured.c3": {
+    "message": "Скачивание"
+  },
+  "home.sc.featured.c4": {
+    "message": "Картинка в картинке"
+  },
+  "home.sc.featured.btn": {
+    "message": "Видеоскрипты"
+  },
+  "home.sc.featured.sites": {
+    "message": "Поддержка 20+ видеосайтов"
+  },
+  "home.sc.adblock.t": {
+    "message": "Блокировка рекламы · Чистый веб"
+  },
+  "home.sc.adblock.d": {
+    "message": "Блокируйте рекламу и всплывающие окна — страница остаётся чистой."
+  },
+  "home.sc.adblock.l": {
+    "message": "Скрипты блокировки рекламы"
+  },
+  "home.sc.shop.t": {
+    "message": "Покупки · Сравнение цен"
+  },
+  "home.sc.shop.d": {
+    "message": "Сравнивайте цены, смотрите историю и применяйте купоны в один клик."
+  },
+  "home.sc.shop.l": {
+    "message": "Помощник покупок"
+  },
+  "home.sc.auto.t": {
+    "message": "Продуктивность · Автоматизация"
+  },
+  "home.sc.auto.d": {
+    "message": "Авто-чек-ин, пакетные действия — удобный набор инструментов."
+  },
+  "home.sc.auto.l": {
+    "message": "Скрипты продуктивности"
+  },
+  "home.sc.read.t": {
+    "message": "Чтение · Перевод"
+  },
+  "home.sc.read.d": {
+    "message": "Тёмная тема, перевод страниц, иммерсивное чтение."
+  },
+  "home.sc.read.l": {
+    "message": "Улучшения чтения"
+  },
+  "home.step.eyebrow": {
+    "message": "СТАРТ ЗА 3 ШАГА"
+  },
+  "home.step.title1": {
+    "message": "30 секунд"
+  },
+  "home.step.title2": {
+    "message": " до первого скрипта"
+  },
+  "home.step.sub": {
+    "message": "Без сложной настройки — три простых шага: установили и пользуетесь."
+  },
+  "home.step1.t": {
+    "message": "Установите расширение"
+  },
+  "home.step1.d": {
+    "message": "Добавьте из магазина Chrome / Edge / Firefox в один клик или установите вручную."
+  },
+  "home.step1.p": {
+    "message": "Добавить в браузер"
+  },
+  "home.step2.t": {
+    "message": "Откройте магазин"
+  },
+  "home.step2.d": {
+    "message": "Тысячи скриптов сообщества ScriptCat — выберите то, что нужно."
+  },
+  "home.step2.p": {
+    "message": "Поиск: скорость видео"
+  },
+  "home.step3.t": {
+    "message": "Установка в один клик"
+  },
+  "home.step3.d": {
+    "message": "Нажмите «Установить» — скрипт сразу заработает на странице."
+  },
+  "home.step3.p": {
+    "message": "Установлен · Уже активен"
+  },
+  "home.feat.eyebrow": {
+    "message": "Ключевые возможности · ПОЧЕМУ SCRIPTCAT"
+  },
+  "home.feat.title1": {
+    "message": "Мощное ядро, "
+  },
+  "home.feat.title2": {
+    "message": "спокойствие"
+  },
+  "home.feat.sub": {
+    "message": "От совместимости до безопасности, от обычных пользователей до разработчиков — ScriptCat закрывает потребности."
+  },
+  "home.feat.compat.t": {
+    "message": "Совместимость с Tampermonkey"
+  },
+  "home.feat.compat.d": {
+    "message": "Полная совместимость с форматом userscript и GM API — миграция существующих скриптов без изменений и без затрат на переход."
+  },
+  "home.feat.compat.b": {
+    "message": "Поддержка GM_* API · тот же блок метаданных"
+  },
+  "home.feat.store.t": {
+    "message": "Магазин скриптов"
+  },
+  "home.feat.store.d": {
+    "message": "Устанавливайте тысячи скриптов сообщества в один клик или публикуйте свои — развиваем экосистему вместе."
+  },
+  "home.feat.store.stat": {
+    "message": "{count} скриптов сообщества"
+  },
+  "home.feat.secure.t": {
+    "message": "Безопасность и надёжность"
+  },
+  "home.feat.secure.d": {
+    "message": "Прозрачные и управляемые разрешения, видимое поведение — вредоносные скрипты останавливаются на входе."
+  },
+  "home.feat.sync.t": {
+    "message": "Облачная синхронизация"
+  },
+  "home.feat.sync.d": {
+    "message": "Скрипты и настройки синхронизируются между устройствами — ничего не теряется при смене или переустановке."
+  },
+  "home.feat.bg.t": {
+    "message": "Фоновые скрипты"
+  },
+  "home.feat.bg.d": {
+    "message": "Уникально: скрипты продолжают работать в фоне без открытой вкладки."
+  },
+  "home.feat.api.t": {
+    "message": "Мощные API"
+  },
+  "home.feat.api.d": {
+    "message": "Богаче GM: файловое хранилище, планировщик задач и кросс-доменные запросы под рукой."
+  },
+  "home.feat.devTag": {
+    "message": "Для разработчиков"
+  },
+  "home.dev.eyebrow": {
+    "message": "Для разработчиков · FOR DEVELOPERS"
+  },
+  "home.dev.title1": {
+    "message": "Превратите браузер в "
+  },
+  "home.dev.title2": {
+    "message": "среду выполнения кода"
+  },
+  "home.dev.sub": {
+    "message": "Фоновые скрипты, богатые API, встроенный редактор и отладка — от первой строки до продакшена в одном месте."
+  },
+  "home.dev.bg.t": {
+    "message": "Фоновые скрипты"
+  },
+  "home.dev.bg.d": {
+    "message": "Не нужно держать вкладку — скрипты работают в фоне."
+  },
+  "home.dev.api.t": {
+    "message": "Мощные API"
+  },
+  "home.dev.api.d": {
+    "message": "Файловое хранилище, cron-расписание и кросс-доменные запросы — всё включено."
+  },
+  "home.dev.editor.t": {
+    "message": "Встроенный редактор"
+  },
+  "home.dev.editor.d": {
+    "message": "Подсветка синтаксиса, умное автодополнение и подсказки об ошибках — писать скрипты приятно."
+  },
+  "home.dev.debug.t": {
+    "message": "Живая отладка"
+  },
+  "home.dev.debug.d": {
+    "message": "Логи, история запусков и отслеживание ошибок — проблемы видны сразу."
+  },
+  "home.dev.docsBtn": {
+    "message": "Читать документацию"
+  },
+  "home.dev.apiBtn": {
+    "message": "Справочник API"
+  },
+  "home.dev.run": {
+    "message": "Запуск"
+  },
+  "home.dev.mock.name": {
+    "message": "Ежедневный чек-ин",
+    "description": "@name value in the editor mock code block"
+  },
+  "home.dev.mock.toast": {
+    "message": "Чек-ин выполнен",
+    "description": "Notification text in the editor mock code block"
+  },
+  "home.comm.eyebrow": {
+    "message": "Open source · ОТКРЫТЫЙ КОД"
+  },
+  "home.comm.title1": {
+    "message": "Создано "
+  },
+  "home.comm.title2": {
+    "message": "сообществом"
+  },
+  "home.comm.sub": {
+    "message": "Полностью открытый, прозрачный и бесплатный. Каждая строка кода доступна для аудита, каждый вклад виден."
+  },
+  "home.comm.btn": {
+    "message": "Внести вклад на GitHub"
+  },
+  "home.cta.eyebrow": {
+    "message": "Бесплатно · Open source · Без рекламы"
+  },
+  "home.cta.h1": {
+    "message": "Готовы дать браузеру"
+  },
+  "home.cta.h2": {
+    "message": "суперспособности"
+  },
+  "home.cta.h3": {
+    "message": "?"
+  },
+  "home.cta.sub": {
+    "message": "Установите из магазина в один клик или скачайте пакет вручную. За 30 секунд — суперспособности для веба."
+  },
+  "home.cta.primary": {
+    "message": "Бесплатная установка для {browser}"
+  },
+  "home.cta.secondary": {
+    "message": "Смотреть скрипты"
+  },
+  "home.cta.stores": {
+    "message": "Поддержка Edge · Chrome · Firefox · ручной пакет"
+  },
+  "home.cta.chip": {
+    "message": "Установлено и работает"
+  },
+  "home.nav.docs": {
+    "message": "Документация"
+  },
+  "home.nav.store": {
+    "message": "Магазин скриптов"
+  },
+  "home.nav.dev": {
+    "message": "Разработчикам"
+  },
+  "home.nav.changelog": {
+    "message": "История изменений"
+  },
+  "home.nav.install": {
+    "message": "Установить"
+  },
+  "home.nav.installTo": {
+    "message": "Добавить в {browser}"
+  },
+  "home.nav.menu": {
+    "message": "Меню"
+  },
+  "home.nav.theme": {
+    "message": "Сменить тему"
+  }
+}
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current.json b/i18n/ru/docusaurus-plugin-content-docs/current.json
new file mode 100644
index 00000000..8101a4d4
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current.json
@@ -0,0 +1,18 @@
+{
+  "version.label": {
+    "message": "Next",
+    "description": "The label for version current"
+  },
+  "sidebar.use.category.服务协议": {
+    "message": "Пользовательское соглашение",
+    "description": "The label for category 服务协议 in sidebar use"
+  },
+  "sidebar.use.category.从其它管理器迁移": {
+    "message": "Миграция из других менеджеров",
+    "description": "The label for category 从其它管理器迁移 in sidebar use"
+  },
+  "sidebar.dev.category.Agent 智能助手": {
+    "message": "Agent",
+    "description": "The label for category Agent 智能助手 in sidebar dev"
+  }
+}
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/about/index.md b/i18n/ru/docusaurus-plugin-content-docs/current/about/index.md
new file mode 100644
index 00000000..cce1ec90
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/about/index.md
@@ -0,0 +1,20 @@
+---
+sidebar: false
+title: О проекте
+description: О ScriptCat
+icon: info
+---
+
+
+## О ScriptCat
+
+Вдохновлённый дизайном Tampermonkey и совместимый со скриптами Tampermonkey, ScriptCat реализует фреймворк выполнения фоновых скриптов и предоставляет ряд специальных API, благодаря которым скрипты могут делать больше, а также удобный редактор, в котором писать и разрабатывать код скриптов комфортно и плавно.
+
+Дорожная карта разработки: [Project #1](https://github.com/scriptscat/scriptcat/projects/1) — там мы публикуем планы разработки. Если у вас есть предложения, создайте [issue](https://github.com/scriptscat/scriptcat/issues), чтобы сообщить нам об этом.
+
+**Если проект оказался полезным, поставьте нам Star ❤❤❤**
+
+## Китайский форум Tampermonkey
+> [Перейти на форум](https://bbs.tampermonkey.net.cn/)
+
+Китайский форум Tampermonkey — сообщество, которое мы создали для разработки и обсуждения скриптов в стиле Tampermonkey. На форуме много учебных материалов по скриптам и опытных участников: там можно обсуждать вопросы и задавать их. Также поддерживаются публикация и установка скриптов — каждый может свободно делиться своими работами.
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-builtin-tools.md b/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-builtin-tools.md
new file mode 100644
index 00000000..63fe76dc
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-builtin-tools.md
@@ -0,0 +1,275 @@
+---
+title: Справочник встроенных инструментов
+---
+
+У Agent есть набор встроенных инструментов, которые AI может автоматически вызывать во время диалога. Эти инструменты доступны по умолчанию в постоянных диалогах, и разработчикам скриптов обычно не нужно вызывать их напрямую — AI сам выбирает подходящий инструмент исходя из намерения пользователя.
+
+Понимание возможностей этих инструментов помогает писать лучшие системные промпты и пользовательские инструменты.
+
+## Получение веб-данных
+
+### web_fetch
+
+Загружает содержимое URL, поддерживая извлечение текста из HTML и суммаризацию LLM.
+
+| Параметр | Тип | Обязательно | Описание |
+|------|------|------|------|
+| `url` | `string` | Да | Целевой URL (только http/https) |
+| `prompt` | `string` | Нет | Промпт суммаризации (при указании LLM используется для сжатия содержимого) |
+| `max_length` | `number` | Нет | Максимальное число символов содержимого |
+
+**Подробности поведения:**
+- Таймаут запроса 30 секунд
+- Из HTML автоматически извлекается основное тело (навигация, боковые панели и т.д. удаляются)
+- JSON-ответы автоматически разбираются
+- Обычный текст возвращается как есть
+- При указании `prompt` загруженное содержимое отправляется в LLM для суммаризации
+
+**Возвращаемое значение:**
+```json
+{
+  "url": "https://example.com",
+  "content_type": "text/html",
+  "content": "The extracted body content...",
+  "truncated": false,
+  "final_url": "https://example.com/redirected"
+}
+```
+
+### web_search
+
+Запрашивает поисковую систему и возвращает структурированные результаты поиска.
+
+| Параметр | Тип | Обязательно | Описание |
+|------|------|------|------|
+| `query` | `string` | Да | Поисковые ключевые слова |
+| `max_results` | `number` | Нет | Максимальное число результатов (по умолчанию 5, максимум 10) |
+
+**Поддерживаемые поисковые системы:**
+
+| Система | Описание | Требуется настройка |
+|------|------|---------|
+| DuckDuckGo | Система по умолчанию | Настройка не нужна |
+| Bing | Microsoft Bing Search | Нужен API Key |
+| Baidu | Baidu Search | API Key не нужен |
+| Google Custom Search | Google Custom Search | Нужны API Key + CSE ID |
+
+Поисковые системы настраиваются в панели управления: Agent → Настройки.
+
+**Возвращаемое значение:**
+```json
+[
+  {
+    "title": "Search result title",
+    "url": "https://example.com/result",
+    "snippet": "Result snippet text..."
+  }
+]
+```
+
+### get_tab_content
+
+Читает отрисованное содержимое страницы заданной вкладки, преобразуя его в структурированный Markdown с аннотациями CSS-селекторов.
+
+| Параметр | Тип | Обязательно | Описание |
+|------|------|------|------|
+| `tab_id` | `number` | Да | ID вкладки |
+| `selector` | `string` | Нет | CSS-селектор; извлекается только совпадающая часть |
+| `prompt` | `string` | Нет | Промпт суммаризации |
+| `max_length` | `number` | Нет | Максимальное число символов содержимого |
+
+Отличие от `web_fetch`: `get_tab_content` читает страницу **уже отрисованную браузером** (включая динамический JS-контент), тогда как `web_fetch` делает новый HTTP-запрос.
+
+**Возвращаемое значение:**
+```json
+{
+  "tab_id": 123,
+  "url": "https://example.com",
+  "title": "Page title",
+  "content": "Structured content...",
+  "truncated": false,
+  "used_selector": "main"
+}
+```
+
+## Управление вкладками
+
+### list_tabs
+
+Запрашивает открытые вкладки с поддержкой нескольких условий фильтрации.
+
+| Параметр | Тип | Обязательно | Описание |
+|------|------|------|------|
+| `url_pattern` | `string` | Нет | Regex для сопоставления URL |
+| `title_pattern` | `string` | Нет | Regex для сопоставления заголовка |
+| `active` | `boolean` | Нет | Только активная вкладка |
+| `window_id` | `number` | Нет | Конкретное окно |
+| `audible` | `boolean` | Нет | Только вкладки, воспроизводящие аудио |
+
+### open_tab
+
+Открывает новую вкладку или навигирует существующую.
+
+| Параметр | Тип | Обязательно | Описание |
+|------|------|------|------|
+| `url` | `string` | Да | Целевой URL |
+| `tab_id` | `number` | Нет | ID существующей вкладки (при указании навигирует её; иначе открывается новая) |
+| `active` | `boolean` | Нет | Активировать ли (по умолчанию `true`) |
+| `window_id` | `number` | Нет | Конкретное окно |
+| `wait_until_loaded` | `boolean` | Нет | Ждать ли окончания загрузки страницы (по умолчанию `true`) |
+
+### close_tab
+
+Закрывает вкладку.
+
+| Параметр | Тип | Обязательно | Описание |
+|------|------|------|------|
+| `tab_id` | `number` | Да | ID вкладки |
+
+### activate_tab
+
+Активирует вкладку и фокусирует её окно.
+
+| Параметр | Тип | Обязательно | Описание |
+|------|------|------|------|
+| `tab_id` | `number` | Да | ID вкладки |
+
+## Файловая система (OPFS)
+
+### opfs_write
+
+Записывает файл в рабочее пространство.
+
+| Параметр | Тип | Обязательно | Описание |
+|------|------|------|------|
+| `path` | `string` | Да | Путь к файлу |
+| `content` | `string` | Да | Содержимое файла (бинарные данные через data URL) |
+
+### opfs_read
+
+Читает файл из рабочего пространства. По умолчанию автоматически определяет тип: текстовые файлы возвращают содержимое, бинарные — blob URL.
+
+| Параметр | Тип | Обязательно | Описание |
+|------|------|------|------|
+| `path` | `string` | Да | Путь к файлу |
+| `mode` | `string` | Нет | `"text"` / `"blob"` / `"auto"` (по умолчанию), принудительный режим возврата |
+| `offset` | `number` | Нет | Начальный номер строки (с 1), только текстовый режим |
+| `limit` | `number` | Нет | Число строк для чтения, только текстовый режим (при более чем 200 строках нужна пагинация) |
+
+### opfs_list
+
+Выводит содержимое каталога.
+
+| Параметр | Тип | Обязательно | Описание |
+|------|------|------|------|
+| `path` | `string` | Нет | Путь к каталогу (по умолчанию корневой) |
+
+### opfs_delete
+
+Удаляет файл или каталог.
+
+| Параметр | Тип | Обязательно | Описание |
+|------|------|------|------|
+| `path` | `string` | Да | Путь к файлу/каталогу |
+
+## Взаимодействие с пользователем
+
+### ask_user
+
+Задаёт пользователю вопрос: свободный ввод или структурированный выбор.
+
+| Параметр | Тип | Обязательно | Описание |
+|------|------|------|------|
+| `question` | `string` | Да | Текст вопроса |
+| `options` | `string[]` | Нет | Список вариантов (при указании — вопрос с выбором) |
+| `multiple` | `boolean` | Нет | Разрешить множественный выбор (по умолчанию `false`) |
+
+**Таймаут:** возвращает `{ answer: null, reason: "timeout" }` после 5 минут без ответа.
+
+**Возвращаемое значение:**
+```json
+{ "answer": "The user's answer text" }
+```
+
+### execute_script
+
+Выполняет JavaScript-код на странице или в песочнице.
+
+| Параметр | Тип | Обязательно | Описание |
+|------|------|------|------|
+| `code` | `string` | Да | Код JavaScript |
+| `target` | `string` | Да | `"page"` или `"sandbox"` |
+| `tab_id` | `number` | Нет | Целевая вкладка, когда `target` — page (по умолчанию текущая активная) |
+| `world` | `string` | Нет | `"MAIN"` или `"ISOLATED"` (по умолчанию), только режим page |
+
+**Сравнение окружений выполнения:**
+
+| Окружение | DOM | JS страницы | Blob URL расширения | Сценарий |
+|------|-----|---------|---------------|---------|
+| page + ISOLATED | Да | Нет | Да | Чтение DOM, извлечение контента |
+| page + MAIN | Да | Да | Нет | Вызов функций страницы |
+| sandbox | Нет | Нет | Нет | Чистые вычисления |
+
+## Подагенты
+
+### agent
+
+Запускает независимый подагент для сложной подзадачи.
+
+| Параметр | Тип | Обязательно | Описание |
+|------|------|------|------|
+| `prompt` | `string` | Да | Описание подзадачи |
+| `description` | `string` | Нет | Короткая метка (3–5 слов, для UI) |
+| `type` | `string` | Нет | Тип подагента (см. ниже); по умолчанию `"general"` |
+| `tab_id` | `number` | Нет | ID вкладки, передаваемый подагенту для работы с ней |
+
+**Типы подагентов:**
+
+| type | Описание | Доступные инструменты |
+|------|------|---------|
+| `researcher` | Поиск информации (только чтение) | web_search, web_fetch, чтение содержимого страницы |
+| `page_operator` | Автоматизация браузера | Управление вкладками, операции DOM, взаимодействие со страницей |
+| `general` | Универсальный (по умолчанию) | Все инструменты |
+
+**Особенности:**
+- У подагента свой независимый контекст диалога
+- Он **не может** использовать `ask_user` или `agent` (чтобы предотвратить рекурсию)
+- События подагента передаются родительскому диалогу через `sub_agent_event`
+
+## Управление задачами
+
+Эта группа инструментов управляет временным списком задач внутри диалога (в памяти, без сохранения).
+
+### create_task
+
+| Параметр | Тип | Обязательно | Описание |
+|------|------|------|------|
+| `subject` | `string` | Да | Заголовок задачи |
+| `description` | `string` | Нет | Подробное описание |
+
+### get_task
+
+| Параметр | Тип | Обязательно |
+|------|------|------|
+| `task_id` | `string` | Да |
+
+### update_task
+
+| Параметр | Тип | Обязательно | Описание |
+|------|------|------|------|
+| `task_id` | `string` | Да | ID задачи |
+| `status` | `string` | Нет | `"pending"` / `"in_progress"` / `"completed"` |
+| `subject` | `string` | Нет | Новый заголовок |
+| `description` | `string` | Нет | Новое описание |
+
+### list_tasks
+
+Без параметров; возвращает краткий список всех задач.
+
+### delete_task
+
+| Параметр | Тип | Обязательно |
+|------|------|------|
+| `task_id` | `string` | Да |
+
+> Инструменты управления задачами в основном позволяют AI отслеживать собственный прогресс при сложных многошаговых задачах; данные задач не сохраняются.
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-conversation.md b/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-conversation.md
new file mode 100644
index 00000000..bbccb10a
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-conversation.md
@@ -0,0 +1,285 @@
+---
+title: API диалогов
+---
+
+`@grant CAT.agent.conversation`
+
+API диалогов — ядро системы Agent: скрипт может создавать AI-диалоги, отправлять сообщения и получать ответы.
+
+## Создание диалога
+
+```javascript
+const conv = await CAT.agent.conversation.create(options?);
+```
+
+### ConversationCreateOptions
+
+| Параметр | Тип | По умолчанию | Описание |
+|------|------|--------|------|
+| `id` | `string` | автогенерация | ID диалога, используется для возобновления существующего |
+| `system` | `string` | — | Пользовательский системный промпт, добавляется после встроенного |
+| `model` | `string` | модель по умолчанию | ID модели (получается после настройки в панели управления) |
+| `maxIterations` | `number` | `20` | Максимальное число итераций цикла вызовов инструментов за один ход диалога |
+| `skills` | `"auto" \| string[]` | — | `"auto"` загружает все Skills автоматически, либо укажите массив имён Skill |
+| `tools` | `ToolDefinition[]` | — | Список пользовательских инструментов (см. ниже) |
+| `commands` | `Record<string, CommandHandler>` | — | Пользовательские команды диалога |
+| `ephemeral` | `boolean` | `false` | Временный диалог, не сохраняется в хранилище |
+| `cache` | `boolean` | `true` | Включить Prompt Caching (снижает расход токенов) |
+| `background` | `boolean` | `false` | Фоновый диалог, продолжающий работу после отключения UI; можно переподключиться через `attach()` |
+
+### Пользовательские инструменты
+
+Скрипт может регистрировать собственные инструменты для вызова AI:
+
+```javascript
+const conv = await CAT.agent.conversation.create({
+  tools: [{
+    name: "get_weather",
+    description: "Get weather information for a given city",
+    parameters: {
+      type: "object",
+      properties: {
+        city: {
+          type: "string",
+          description: "City name"
+        },
+        unit: {
+          type: "string",
+          enum: ["celsius", "fahrenheit"],
+          description: "Temperature unit"
+        }
+      },
+      required: ["city"]
+    },
+    handler: async (args) => {
+      // args = { city: "Beijing", unit: "celsius" }
+      const data = await fetchWeather(args.city, args.unit);
+      return { temperature: data.temp, condition: data.condition };
+    }
+  }]
+});
+```
+
+`parameters` инструмента следует спецификации [JSON Schema](https://json-schema.org/); AI использует `description`, чтобы понять, когда и как вызывать инструмент.
+
+### Пользовательские команды
+
+Можно регистрировать пользовательские команды, начинающиеся с `/`:
+
+```javascript
+const conv = await CAT.agent.conversation.create({
+  commands: {
+    "/export": async (args) => {
+      // triggered when the user types "/export pdf"
+      await exportToPdf(args);
+      return "Export complete";
+    }
+  }
+});
+```
+
+Встроенные команды: `/new` (новый диалог), `/reset` (сброс контекста), `/compact` (сжатие истории сообщений).
+
+## Получение существующего диалога
+
+```javascript
+const conv = await CAT.agent.conversation.get(conversationId);
+// returns null if the conversation doesn't exist
+```
+
+## Методы ConversationInstance
+
+### chat — синхронный чат
+
+```javascript
+const reply = await conv.chat(content, options?);
+```
+
+Отправляет сообщение и ждёт полного ответа. Пока AI отвечает, он может вызывать инструменты; `chat` ждёт завершения всех вызовов, прежде чем вернуть итоговый результат.
+
+**Параметры:**
+
+| Параметр | Тип | Описание |
+|------|------|------|
+| `content` | `string \| ContentBlock[]` | Содержимое сообщения: текст или мультимодальные блоки |
+| `options.tools` | `ToolDefinition[]` | Дополнительные инструменты только для этого вызова (объединяются с заданными при создании) |
+
+**Возвращаемое значение, ChatReply:**
+
+| Поле | Тип | Описание |
+|------|------|------|
+| `content` | `string \| ContentBlock[]` | Содержимое ответа AI |
+| `thinking` | `string` | Процесс рассуждения модели (поддерживают только некоторые модели) |
+| `toolCalls` | `ToolCall[]` | Зафиксированные вызовы инструментов в этом ответе |
+| `usage` | `{ inputTokens, outputTokens }` | Использование токенов |
+| `command` | `boolean` | Был ли этот ответ вызван командой |
+
+### chatStream — потоковый чат
+
+```javascript
+const stream = await conv.chatStream(content, options?);
+for await (const chunk of stream) {
+  // handle streaming events
+}
+```
+
+Получает ответ AI в реальном времени — удобно, когда нужно постепенно отображать вывод.
+
+**Типы событий StreamChunk:**
+
+| type | Поле | Описание |
+|------|------|------|
+| `content_delta` | `content: string` | Инкрементальный текстовый контент |
+| `thinking_delta` | `thinking: string` | Инкрементальный контент рассуждений |
+| `tool_call` | `toolCall: ToolCall` | Информация о вызове инструмента (при смене состояния) |
+| `content_block` | `block: ContentBlock` | Блок контента (изображение, файл и т.д.) |
+| `done` | `usage: { inputTokens, outputTokens }` | Ход диалога завершён |
+| `error` | `error: string, errorCode?: string` | Произошла ошибка |
+
+**Коды ошибок (errorCode):**
+
+| Код ошибки | Описание |
+|--------|------|
+| `rate_limit` | Лимит частоты API; обычно повторяется автоматически |
+| `auth` | Ошибка аутентификации; проверьте API Key |
+| `tool_timeout` | Таймаут выполнения инструмента |
+| `max_iterations` | Достигнут максимум итераций цикла вызовов инструментов |
+| `api_error` | Другая ошибка API |
+
+### getMessages — получить историю сообщений
+
+```javascript
+const messages = await conv.getMessages();
+```
+
+Возвращает `ChatMessage[]` со всеми сообщениями диалога.
+
+**Структура ChatMessage:**
+
+| Поле | Тип | Описание |
+|------|------|------|
+| `id` | `string` | ID сообщения |
+| `role` | `"user" \| "assistant" \| "system" \| "tool"` | Роль сообщения |
+| `content` | `string \| ContentBlock[]` | Содержимое сообщения |
+| `thinking` | `string` | Процесс рассуждения (сообщения assistant) |
+| `toolCalls` | `ToolCall[]` | Записи вызовов инструментов (сообщения assistant) |
+| `toolCallId` | `string` | Соответствующий ID вызова инструмента (сообщения tool) |
+| `usage` | `{ inputTokens, outputTokens }` | Использование токенов |
+| `createtime` | `number` | Временная метка создания |
+
+### clear — очистить диалог
+
+```javascript
+await conv.clear();
+```
+
+Очищает всю историю сообщений диалога.
+
+### save — сохранить диалог
+
+```javascript
+await conv.save();
+```
+
+Сохраняет метаданные диалога в хранилище. Временные диалоги (`ephemeral: true`) по умолчанию не сохраняются; вызов этого метода превращает их в постоянные.
+
+### attach — переподключиться к фоновому диалогу
+
+```javascript
+const stream = await conv.attach();
+for await (const chunk of stream) {
+  // receive real-time events from the background conversation
+}
+```
+
+Если диалог создан с `background: true` и всё ещё работает в фоне, можно переподключиться через `attach()` и получать последующие потоковые события.
+
+### Свойства экземпляра
+
+| Свойство | Тип | Описание |
+|------|------|------|
+| `id` | `string` | ID диалога |
+| `title` | `string` | Заголовок диалога |
+| `modelId` | `string` | ID используемой модели |
+
+## Мультимодальный контент
+
+Содержимое сообщения может быть обычной строкой или массивом `ContentBlock[]` для поддержки нескольких модальностей:
+
+```javascript
+// Send text + an image
+await conv.chat([
+  { type: "text", text: "Please analyze the content of this image" },
+  { type: "image", attachmentId: "img-id", mimeType: "image/png" }
+]);
+```
+
+### Типы ContentBlock
+
+| type | Обязательные поля | Описание |
+|------|---------|------|
+| `text` | `text: string` | Текстовое содержимое |
+| `image` | `attachmentId: string, mimeType: string` | Изображение; модель должна поддерживать vision |
+| `file` | `attachmentId: string, mimeType: string, name: string` | Файл |
+| `audio` | `attachmentId: string, mimeType: string` | Аудио |
+
+## Временные и постоянные диалоги
+
+| Свойство | Постоянный диалог (по умолчанию) | Временный диалог |
+|------|-------------------|---------------------|
+| Хранение сообщений | Сохраняется в OPFS | Только в памяти |
+| Встроенные инструменты | Все доступны | Не включены; нужно передавать через `tools` |
+| Список диалогов | Виден | Не виден |
+| Prompt Caching | Поддерживается | Можно отключить |
+| Сценарий | Обычный диалог | Лёгкие разовые задачи, быстрые вопросы |
+
+## Управление контекстом
+
+### Автосжатие
+
+Когда использование контекста диалога превышает **80%** окна контекста модели, система автоматически вызывает LLM для генерации сводки истории, заменяя старые сообщения и освобождая место.
+
+### Prompt Caching
+
+Включён по умолчанию. Для моделей Anthropic системный промпт и история сообщений кэшируются, что может существенно снизить расход токенов и задержку на повторных ходах диалога.
+
+Можно отключить через `cache: false`:
+
+```javascript
+const conv = await CAT.agent.conversation.create({ cache: false });
+```
+
+## Полный пример
+
+```javascript
+// ==UserScript==
+// @name        Smart Translation Assistant
+// @match       *://*/*
+// @grant       CAT.agent.conversation
+// @grant       CAT.agent.dom
+// ==/UserScript==
+
+// Create a conversation with a custom tool
+const conv = await CAT.agent.conversation.create({
+  system: "You are a translation assistant. The user will give you web page content — please translate it into Chinese.",
+  tools: [{
+    name: "get_selection",
+    description: "Get the text the user has selected on the page",
+    parameters: { type: "object", properties: {} },
+    handler: async () => {
+      return { text: window.getSelection()?.toString() || "No text selected" };
+    }
+  }]
+});
+
+// Stream the translation result
+const stream = await conv.chatStream("Please get the selected text and translate it into Chinese");
+let result = "";
+for await (const chunk of stream) {
+  if (chunk.type === "content_delta") {
+    result += chunk.content;
+    // update the UI in real time
+    updateTranslationUI(result);
+  }
+}
+```
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-dom.md b/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-dom.md
new file mode 100644
index 00000000..3ed47f69
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-dom.md
@@ -0,0 +1,336 @@
+---
+title: API DOM
+---
+
+`@grant CAT.agent.dom`
+
+API DOM предоставляет полный набор возможностей автоматизации страниц браузера: навигацию, чтение содержимого, скриншоты, взаимодействие с формами и мониторинг DOM.
+
+## Управление вкладками
+
+### listTabs — список вкладок
+
+```javascript
+const tabs = await CAT.agent.dom.listTabs();
+```
+
+Возвращает информацию о каждой открытой вкладке.
+
+**Возвращаемое значение, TabInfo[]:**
+
+| Поле | Тип | Описание |
+|------|------|------|
+| `tabId` | `number` | ID вкладки |
+| `url` | `string` | Текущий URL |
+| `title` | `string` | Заголовок страницы |
+| `active` | `boolean` | Является ли текущей активной вкладкой |
+| `windowId` | `number` | ID окна, которому принадлежит |
+| `discarded` | `boolean` | Была ли выгружена (приостановлена) |
+
+## Навигация
+
+### navigate — перейти на страницу
+
+```javascript
+const result = await CAT.agent.dom.navigate(url, options?);
+```
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|------|------|--------|------|
+| `url` | `string` | — | Целевой URL (обязательно) |
+| `options.tabId` | `number` | текущая активная вкладка | Указать вкладку |
+| `options.waitUntil` | `boolean` | `true` | Ждать ли окончания загрузки страницы |
+| `options.timeout` | `number` | `30000` | Таймаут в миллисекундах |
+
+**Возвращаемое значение, NavigateResult:**
+
+```typescript
+{ tabId: number; url: string; title: string }
+```
+
+## Чтение содержимого
+
+### readPage — прочитать содержимое страницы
+
+```javascript
+const page = await CAT.agent.dom.readPage(options?);
+```
+
+Преобразует DOM страницы в структурированный текст, автоматически удаляя нерелевантные элементы вроде `<script>`, `<style>`, `<noscript>`, `<svg>` и `<link[rel=stylesheet]>`.
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|------|------|--------|------|
+| `options.tabId` | `number` | текущая активная вкладка | Указать вкладку |
+| `options.selector` | `string` | — | CSS-селектор; возвращает только содержимое совпадающих элементов |
+| `options.maxLength` | `number` | — | Максимальное число символов; сверх — обрезка |
+| `options.removeTags` | `string[]` | — | Дополнительные имена тегов для удаления |
+
+**Возвращаемое значение, PageContent:**
+
+| Поле | Тип | Описание |
+|------|------|------|
+| `title` | `string` | Заголовок страницы |
+| `url` | `string` | URL страницы |
+| `html` | `string` | Обработанное текстовое содержимое страницы |
+| `truncated` | `boolean` | Было ли содержимое обрезано |
+| `totalLength` | `number` | Исходная полная длина содержимого |
+
+### screenshot — сделать скриншот
+
+```javascript
+const shot = await CAT.agent.dom.screenshot(options?);
+```
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|------|------|--------|------|
+| `options.tabId` | `number` | текущая активная вкладка | Указать вкладку |
+| `options.quality` | `number` | `80` | Качество JPEG (0-100) |
+| `options.fullPage` | `boolean` | `false` | Снять всю страницу |
+| `options.selector` | `string` | — | CSS-селектор; снимает только область совпадающего элемента |
+| `options.saveTo` | `string` | — | Путь сохранения в рабочем пространстве OPFS |
+
+**Возвращаемое значение, ScreenshotResult:**
+
+| Поле | Тип | Описание |
+|------|------|------|
+| `dataUrl` | `string` | Data URL в base64 |
+| `path` | `string` | Путь сохранения в OPFS (если использован `saveTo`) |
+| `size` | `number` | Размер файла (если использован `saveTo`) |
+
+**Выбор режима скриншота:**
+
+| Сценарий | Поведение |
+|------|------|
+| Используется `selector` | Границы элемента находятся через CDP, скриншот обрезается |
+| Фоновая вкладка | Пытается CDP-скриншот; при неудаче активирует вкладку и использует `captureVisibleTab` |
+| Передняя вкладка | Сразу использует `captureVisibleTab` |
+
+```javascript
+// Save a screenshot to OPFS
+const shot = await CAT.agent.dom.screenshot({
+  saveTo: "screenshots/page.png",
+  quality: 90
+});
+console.log(`Saved to ${shot.path}, size ${shot.size} bytes`);
+```
+
+## Взаимодействие со страницей
+
+### click — клик по элементу
+
+```javascript
+const result = await CAT.agent.dom.click(selector, options?);
+```
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|------|------|--------|------|
+| `selector` | `string` | — | CSS-селектор (обязательно) |
+| `options.tabId` | `number` | текущая активная вкладка | Указать вкладку |
+| `options.trusted` | `boolean` | `false` | Использовать CDP для настоящего события мыши |
+
+**Возвращаемое значение, ActionResult:**
+
+| Поле | Тип | Описание |
+|------|------|------|
+| `success` | `boolean` | Успешность |
+| `navigated` | `boolean` | Привёл ли клик к навигации страницы |
+| `url` | `string` | Новый URL после навигации |
+| `newTab` | `boolean` | Была ли открыта новая вкладка |
+
+**trusted и обычный клик:**
+
+- `trusted: false` (по умолчанию) — симулирует `element.click()` через внедрённый JS; быстро, но некоторые сайты могут распознать как ненастоящее событие
+- `trusted: true` — отправляет настоящее событие мыши через Chrome DevTools Protocol, ведёт себя как действие реального пользователя, но требует разрешение debugger
+
+### fill — заполнить форму
+
+```javascript
+const result = await CAT.agent.dom.fill(selector, value, options?);
+```
+
+**Параметры:**
+
+| Параметр | Тип | Описание |
+|------|------|------|
+| `selector` | `string` | CSS-селектор (обязательно) |
+| `value` | `string` | Значение для ввода (обязательно) |
+| `options.tabId` | `number` | Указать вкладку |
+| `options.trusted` | `boolean` | Использовать CDP для имитации ввода с клавиатуры |
+
+**Поведение:**
+- Обычный режим: устанавливает `element.value` и отправляет событие `input`
+- Режим trusted: CDP фокусирует элемент → вводит посимвольно
+
+### scroll — прокрутить страницу
+
+```javascript
+const result = await CAT.agent.dom.scroll(direction, options?);
+```
+
+**Параметры:**
+
+| Параметр | Тип | Описание |
+|------|------|------|
+| `direction` | `"up" \| "down" \| "top" \| "bottom"` | Направление прокрутки (обязательно) |
+| `options.tabId` | `number` | Указать вкладку |
+| `options.selector` | `string` | Прокрутить конкретный контейнер вместо всей страницы |
+
+**Возвращаемое значение, ScrollResult:**
+
+| Поле | Тип | Описание |
+|------|------|------|
+| `scrollTop` | `number` | Позиция прокрутки после действия |
+| `scrollHeight` | `number` | Полная высота содержимого |
+| `clientHeight` | `number` | Высота видимой области |
+| `atBottom` | `boolean` | Достигнут ли низ |
+
+### waitFor — ждать элемент
+
+```javascript
+const result = await CAT.agent.dom.waitFor(selector, options?);
+```
+
+Опрашивает появление указанного элемента на странице (проверка каждые 500 мс).
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|------|------|--------|------|
+| `selector` | `string` | — | CSS-селектор (обязательно) |
+| `options.tabId` | `number` | текущая активная вкладка | Указать вкладку |
+| `options.timeout` | `number` | `10000` | Таймаут в миллисекундах |
+
+**Возвращаемое значение, WaitForResult:**
+
+| Поле | Тип | Описание |
+|------|------|------|
+| `found` | `boolean` | Найден ли элемент |
+| `element` | `object` | Информация об элементе (только при found=true) |
+| `element.selector` | `string` | Совпавший селектор |
+| `element.tag` | `string` | Имя тега |
+| `element.text` | `string` | Текстовое содержимое |
+| `element.role` | `string` | ARIA role |
+| `element.type` | `string` | input type |
+| `element.visible` | `boolean` | Видимость |
+
+## Выполнение скриптов
+
+### executeScript — выполнить JavaScript
+
+```javascript
+const result = await CAT.agent.dom.executeScript(code, options?);
+```
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|------|------|--------|------|
+| `code` | `string` | — | Код JavaScript (обязательно) |
+| `options.tabId` | `number` | текущая активная вкладка | Указать вкладку |
+| `options.world` | `"MAIN" \| "ISOLATED"` | `"ISOLATED"` | Окружение выполнения |
+
+**Два окружения выполнения:**
+
+| Окружение | Описание | Сценарий |
+|------|------|---------|
+| **ISOLATED** | Изолированное окружение расширения, отделённое от JS страницы | Манипуляции DOM, чтение контента, использование blob URL расширения |
+| **MAIN** | Собственное окружение страницы, общий объект `window` | Вызов JS-функций страницы, чтение переменных страницы |
+
+```javascript
+// ISOLATED — safely read the DOM
+const title = await CAT.agent.dom.executeScript(
+  "return document.querySelector('h1')?.textContent",
+  { world: "ISOLATED" }
+);
+
+// MAIN — call a JS function on the page
+const data = await CAT.agent.dom.executeScript(
+  "return window.__APP_STATE__",
+  { world: "MAIN" }
+);
+```
+
+> Код оборачивается в `new Function()` для выполнения и поддерживает `return`. Таймаут — 30 секунд.
+
+## Мониторинг DOM
+
+Отслеживает изменения DOM и события диалогов на странице через Chrome DevTools Protocol.
+
+### startMonitor — начать мониторинг
+
+```javascript
+await CAT.agent.dom.startMonitor(tabId);
+```
+
+Начинает мониторинг изменений DOM и диалогов (alert/confirm/prompt) на указанной вкладке.
+
+### stopMonitor — остановить мониторинг
+
+```javascript
+const result = await CAT.agent.dom.stopMonitor(tabId);
+```
+
+Останавливает мониторинг и возвращает собранные изменения.
+
+**Возвращаемое значение, MonitorResult:**
+
+| Поле | Тип | Описание |
+|------|------|------|
+| `dialogs` | `Array<{ type, message }>` | Список диалогов |
+| `addedNodes` | `Array<{ tag, id?, class?, role?, text }>` | Сводка вновь добавленных узлов DOM |
+
+### peekMonitor — проверить статус мониторинга
+
+```javascript
+const status = await CAT.agent.dom.peekMonitor(tabId);
+```
+
+Неразрушающе проверяет текущий статус мониторинга.
+
+**Возвращаемое значение, MonitorStatus:**
+
+| Поле | Тип | Описание |
+|------|------|------|
+| `hasChanges` | `boolean` | Есть ли изменения |
+| `dialogCount` | `number` | Число диалогов |
+| `nodeCount` | `number` | Число вновь добавленных узлов |
+
+## Полный пример
+
+```javascript
+// ==UserScript==
+// @name        Automatic Form Filling
+// @match       https://example.com/form
+// @grant       CAT.agent.dom
+// ==/UserScript==
+
+// Wait for the form to load
+await CAT.agent.dom.waitFor("form#signup", { timeout: 5000 });
+
+// Fill in the form
+await CAT.agent.dom.fill("input[name=username]", "test_user");
+await CAT.agent.dom.fill("input[name=email]", "test@example.com");
+
+// Check the agreement checkbox
+await CAT.agent.dom.click("input[type=checkbox]#agree");
+
+// Screenshot the filled-in result
+await CAT.agent.dom.screenshot({
+  selector: "form#signup",
+  saveTo: "screenshots/form-filled.png"
+});
+
+// Click submit
+const result = await CAT.agent.dom.click("button[type=submit]", { trusted: true });
+if (result.navigated) {
+  console.log("Form submitted successfully, navigated to:", result.url);
+}
+```
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-mcp.md b/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-mcp.md
new file mode 100644
index 00000000..90339d37
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-mcp.md
@@ -0,0 +1,169 @@
+---
+title: API управления MCP
+---
+
+`@grant CAT.agent.mcp`
+
+API управления MCP ([Model Context Protocol](https://modelcontextprotocol.io/)) позволяет скрипту управлять подключениями к MCP-серверам. Инструменты, которые предоставляет MCP-сервер, автоматически регистрируются у Agent для вызова в AI-диалогах.
+
+## MCP-серверы
+
+MCP Client в ScriptCat использует транспортный протокол **Streamable HTTP** (JSON-RPC 2.0 поверх POST) и поддерживает версию протокола MCP `2025-03-26`.
+
+MCP-сервер может предоставлять три вида возможностей:
+
+| Возможность | Описание |
+|------|------|
+| **Tools** | Функции-инструменты, автоматически регистрируемые как вызываемые Agent инструменты |
+| **Resources** | Читаемые ресурсы (текст/бинарные) |
+| **Prompts** | Шаблоны промптов с поддержкой параметров |
+
+## listServers — список серверов
+
+```javascript
+const servers = await CAT.agent.mcp.listServers();
+```
+
+**Возвращаемое значение, MCPServerConfig[]:**
+
+| Поле | Тип | Описание |
+|------|------|------|
+| `id` | `string` | ID сервера |
+| `name` | `string` | Отображаемое имя |
+| `url` | `string` | Адрес HTTP-эндпоинта |
+| `apiKey` | `string` | API Key (необязательно) |
+| `headers` | `Record<string, string>` | Пользовательские заголовки запроса (необязательно) |
+| `enabled` | `boolean` | Включён ли |
+| `createtime` | `number` | Временная метка создания |
+| `updatetime` | `number` | Временная метка обновления |
+
+## getServer — детали сервера
+
+```javascript
+const server = await CAT.agent.mcp.getServer(serverId);
+```
+
+## addServer — добавить сервер
+
+```javascript
+const server = await CAT.agent.mcp.addServer({
+  name: "My MCP Server",
+  url: "https://mcp.example.com/api",
+  apiKey: "sk-xxx",          // optional
+  headers: {                  // optional custom headers
+    "X-Custom": "value"
+  },
+  enabled: true
+});
+```
+
+## updateServer — обновить сервер
+
+```javascript
+await CAT.agent.mcp.updateServer(serverId, {
+  name: "New name",
+  enabled: false
+});
+```
+
+## removeServer — удалить сервер
+
+```javascript
+await CAT.agent.mcp.removeServer(serverId);
+```
+
+## testConnection — проверить соединение
+
+```javascript
+await CAT.agent.mcp.testConnection(serverId);
+```
+
+Пытается подключиться к серверу и обменяться версиями протокола; при успехе ничего не возвращает, при сбое выбрасывает исключение.
+
+## listTools — список инструментов
+
+```javascript
+const tools = await CAT.agent.mcp.listTools(serverId);
+```
+
+Возвращает список инструментов сервера; каждый инструмент включает `name`, `description` и `inputSchema` (определение параметров JSON Schema).
+
+Инструменты включённых MCP-серверов автоматически регистрируются у Agent с именами формата `mcp_{serverId}_{toolName}`.
+
+## listResources — список ресурсов
+
+```javascript
+const resources = await CAT.agent.mcp.listResources(serverId);
+```
+
+Возвращает список ресурсов, которые может предоставить сервер.
+
+## readResource — прочитать ресурс
+
+```javascript
+const result = await CAT.agent.mcp.readResource(serverId, uri);
+```
+
+**Параметры:**
+
+| Параметр | Тип | Описание |
+|------|------|------|
+| `serverId` | `string` | ID сервера |
+| `uri` | `string` | URI ресурса |
+
+Возвращает содержимое ресурса.
+
+## listPrompts — список шаблонов промптов
+
+```javascript
+const prompts = await CAT.agent.mcp.listPrompts(serverId);
+```
+
+## getPrompt — получить промпт
+
+```javascript
+const messages = await CAT.agent.mcp.getPrompt(serverId, promptName, args?);
+```
+
+**Параметры:**
+
+| Параметр | Тип | Описание |
+|------|------|------|
+| `serverId` | `string` | ID сервера |
+| `promptName` | `string` | Имя промпта |
+| `args` | `Record<string, string>` | Параметры промпта |
+
+## Полный пример
+
+```javascript
+// ==UserScript==
+// @name        MCP Tool Management
+// @match       *://*/*
+// @grant       CAT.agent.mcp
+// @grant       CAT.agent.conversation
+// ==/UserScript==
+
+// Add an MCP server
+const server = await CAT.agent.mcp.addServer({
+  name: "Knowledge Base",
+  url: "https://my-kb.example.com/mcp",
+  apiKey: "my-api-key",
+  enabled: true
+});
+
+// Test the connection
+try {
+  await CAT.agent.mcp.testConnection(server.id);
+  console.log("Connected successfully!");
+} catch (e) {
+  console.error("Connection failed:", e);
+}
+
+// See the available tools
+const tools = await CAT.agent.mcp.listTools(server.id);
+console.log("Available tools:", tools.map(t => t.name));
+
+// Use it in a conversation — MCP tools are registered automatically, so the AI can call them directly
+const conv = await CAT.agent.conversation.create();
+const reply = await conv.chat("Please use the knowledge base to search for information about ScriptCat");
+```
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-model.md b/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-model.md
new file mode 100644
index 00000000..a4603aa0
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-model.md
@@ -0,0 +1,91 @@
+---
+title: API запроса моделей
+---
+
+`@grant CAT.agent.model`
+
+API запроса моделей предоставляет доступ только для чтения к информации о моделях, которые пользователь настроил в панели управления. Из соображений безопасности API Key никогда не передаётся скриптам.
+
+## list — список всех моделей
+
+```javascript
+const models = await CAT.agent.model.list();
+```
+
+**Возвращаемое значение, ModelSummary[]:**
+
+| Поле | Тип | Описание |
+|------|------|------|
+| `id` | `string` | ID модели |
+| `name` | `string` | Отображаемое имя |
+| `provider` | `"openai" \| "anthropic" \| "zhipu"` | Тип провайдера |
+| `apiBaseUrl` | `string` | Базовый адрес API |
+| `model` | `string` | Идентификатор модели (например, `gpt-4o`, `claude-sonnet-4-20250514`) |
+| `maxTokens` | `number` | Максимальное число выходных токенов |
+| `contextWindow` | `number` | Размер окна контекста |
+| `supportsVision` | `boolean` | Поддержка визуального ввода (изображения) |
+| `supportsImageOutput` | `boolean` | Поддержка генерации изображений |
+
+> Примечание: возвращаемое значение **не включает** поле `apiKey`.
+
+## get — получить конкретную модель
+
+```javascript
+const model = await CAT.agent.model.get(modelId);
+```
+
+Возвращает `null`, если модель не существует.
+
+## getDefault — получить ID модели по умолчанию
+
+```javascript
+const defaultId = await CAT.agent.model.getDefault();
+```
+
+Возвращает строку ID модели по умолчанию, заданной пользователем.
+
+## getSummary — получить сводку списка моделей
+
+```javascript
+const summary = await CAT.agent.model.getSummary();
+```
+
+Возвращает текстовую сводку всех настроенных моделей, подходящую для прямой вставки в промпт как справочник для AI.
+
+## Сценарии использования
+
+### Выбор модели пользователем
+
+```javascript
+// ==UserScript==
+// @name        Model Selection Example
+// @grant       CAT.agent.model
+// @grant       CAT.agent.conversation
+// ==/UserScript==
+
+const models = await CAT.agent.model.list();
+const defaultId = await CAT.agent.model.getDefault();
+
+// Present these to the user to choose from
+const selectedModel = models.find(m => m.supportsVision) || models[0];
+
+const conv = await CAT.agent.conversation.create({
+  model: selectedModel.id
+});
+```
+
+### Проверка возможностей модели
+
+```javascript
+const model = await CAT.agent.model.get("my-model-id");
+if (model?.supportsVision) {
+  // can send images
+  await conv.chat([
+    { type: "text", text: "Please describe this image" },
+    { type: "image", attachmentId: imgId, mimeType: "image/png" }
+  ]);
+} else {
+  // text only
+  await conv.chat("Please describe the content of the current page");
+}
+```
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-opfs.md b/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-opfs.md
new file mode 100644
index 00000000..ae220936
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-opfs.md
@@ -0,0 +1,204 @@
+---
+title: API файлов OPFS
+---
+
+`@grant CAT.agent.opfs`
+
+API файлов OPFS (Origin Private File System) позволяет скрипту читать и записывать файлы в рабочем пространстве Agent. Все пути относительны к каталогу `agents/workspace/`.
+
+## write — записать файл
+
+```javascript
+const result = await CAT.agent.opfs.write(path, content);
+```
+
+**Параметры:**
+
+| Параметр | Тип | Описание |
+|------|------|------|
+| `path` | `string` | Путь к файлу (обязательно); поддерживаются вложенные каталоги |
+| `content` | `string \| Blob` | Содержимое файла |
+
+**Поддерживаемые форматы `content`:**
+
+| Формат | Описание |
+|------|------|
+| Обычная строка | Сохраняется как текстовый файл UTF-8 |
+| Строка data URL | Автоматически декодируется и сохраняется как бинарные данные (например, `data:image/png;base64,...`) |
+| Объект `Blob` | Сохраняется напрямую как бинарные данные |
+
+**Возвращаемое значение, WriteResult:**
+
+| Поле | Тип | Описание |
+|------|------|------|
+| `path` | `string` | Путь, по которому сохранён файл |
+| `size` | `number` | Размер файла в байтах |
+
+```javascript
+// Write a text file
+await CAT.agent.opfs.write("data/config.json", JSON.stringify({ key: "value" }));
+
+// Write a binary file (data URL)
+const canvas = document.createElement("canvas");
+const dataUrl = canvas.toDataURL("image/png");
+await CAT.agent.opfs.write("images/chart.png", dataUrl);
+```
+
+> Если родительские каталоги в пути не существуют, они создаются автоматически. Если файл уже существует, его содержимое перезаписывается.
+
+## read — прочитать файл
+
+```javascript
+const result = await CAT.agent.opfs.read(path, format?);
+```
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|------|------|--------|------|
+| `path` | `string` | — | Путь к файлу (обязательно) |
+| `format` | `"text" \| "bloburl"` | `"text"` | Формат чтения |
+
+**Возвращаемое значение, ReadResult:**
+
+| Поле | Тип | Условие | Описание |
+|------|------|------|------|
+| `path` | `string` | Всегда | Путь к файлу |
+| `size` | `number` | Всегда | Размер файла |
+| `content` | `string` | format="text" | Текстовое содержимое файла |
+| `blobUrl` | `string` | format="bloburl" | Blob URL |
+| `mimeType` | `string` | format="bloburl" | MIME-тип |
+
+**Два режима чтения:**
+
+```javascript
+// Text mode — good for JSON and text files
+const config = await CAT.agent.opfs.read("data/config.json");
+const data = JSON.parse(config.content);
+
+// Blob URL mode — good for images and binary files
+const image = await CAT.agent.opfs.read("images/chart.png", "bloburl");
+// image.blobUrl = "blob:chrome-extension://xxx/yyy"
+// This URL can be used inside an executeScript call in the ISOLATED world
+```
+
+**Автоматически распознаваемые MIME-типы:**
+
+| Расширение | MIME-тип |
+|--------|----------|
+| `.jpg` / `.jpeg` | `image/jpeg` |
+| `.png` | `image/png` |
+| `.gif` | `image/gif` |
+| `.webp` | `image/webp` |
+| `.svg` | `image/svg+xml` |
+| `.mp3` | `audio/mpeg` |
+| `.wav` | `audio/wav` |
+| `.mp4` | `video/mp4` |
+| `.pdf` | `application/pdf` |
+| `.json` | `application/json` |
+| `.txt` | `text/plain` |
+| `.html` | `text/html` |
+| `.css` | `text/css` |
+| `.js` | `application/javascript` |
+| Другое | `application/octet-stream` |
+
+## list — список каталога
+
+```javascript
+const entries = await CAT.agent.opfs.list(path?);
+```
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|------|------|--------|------|
+| `path` | `string` | `""` | Путь к каталогу; пустая строка означает корневой каталог |
+
+**Возвращаемое значение, FileEntry[]:**
+
+| Поле | Тип | Описание |
+|------|------|------|
+| `name` | `string` | Имя файла/каталога |
+| `type` | `"file" \| "directory"` | Тип |
+| `size` | `number` | Размер файла (только для типа `file`) |
+
+```javascript
+const entries = await CAT.agent.opfs.list("data/");
+for (const entry of entries) {
+  if (entry.type === "file") {
+    console.log(`${entry.name} (${entry.size} bytes)`);
+  } else {
+    console.log(`${entry.name}/`);
+  }
+}
+```
+
+## delete — удалить файл или каталог
+
+```javascript
+const result = await CAT.agent.opfs.delete(path);
+```
+
+Поддерживает рекурсивное удаление каталога и всего его содержимого.
+
+**Возвращаемое значение:**
+
+```typescript
+{ success: true }
+```
+
+## readAttachment — прочитать вложение
+
+```javascript
+const result = await CAT.agent.opfs.readAttachment(attachmentId);
+```
+
+Читает данные вложений (изображения, файлы и т.д.) из диалога. ID вложения берётся из `ContentBlock.attachmentId` в сообщении.
+
+**Параметры:**
+
+| Параметр | Тип | Описание |
+|------|------|------|
+| `attachmentId` | `string` | ID вложения (обязательно) |
+
+**Возвращаемое значение:**
+
+| Поле | Тип | Описание |
+|------|------|------|
+| `id` | `string` | ID вложения |
+| `data` | `Blob` | Бинарные данные вложения |
+| `size` | `number` | Размер файла в байтах |
+| `mimeType` | `string` | MIME-тип |
+
+```javascript
+// Read an image attachment generated by the AI in a conversation
+const messages = await conv.getMessages();
+const lastMsg = messages[messages.length - 1];
+const imageBlock = lastMsg.content.find(b => b.type === "image");
+if (imageBlock) {
+  const attachment = await CAT.agent.opfs.readAttachment(imageBlock.attachmentId);
+  console.log(`Attachment size: ${attachment.size}, type: ${attachment.mimeType}`);
+}
+```
+
+## Замечания по использованию Blob URL
+
+- Blob URL имеют вид `blob:chrome-extension://xxx/yyy`
+- **Можно использовать только в мире ISOLATED** (окружение `executeScript` по умолчанию)
+- Blob URL расширения недоступны из мира MAIN (окружение страницы)
+- Время жизни blob URL привязано к сессии расширения
+
+```javascript
+// Correct: use the blob URL in the ISOLATED world
+const img = await CAT.agent.opfs.read("images/photo.png", "bloburl");
+await CAT.agent.dom.executeScript(`
+  const img = document.createElement("img");
+  img.src = "${img.blobUrl}";
+  document.body.appendChild(img);
+`, { world: "ISOLATED" });
+
+// Wrong: not accessible from the MAIN world
+await CAT.agent.dom.executeScript(`
+  fetch("${img.blobUrl}") // this will fail!
+`, { world: "MAIN" });
+```
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-skill-dev.md b/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-skill-dev.md
new file mode 100644
index 00000000..2873da23
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-skill-dev.md
@@ -0,0 +1,420 @@
+---
+title: Руководство по разработке Skill
+---
+
+Skill — пакет расширения системы Agent, состоящий из **промптов + скриптов инструментов + справочных материалов**. Skills позволяют внедрять в AI предметные знания и пользовательские возможности инструментов.
+
+## Структура каталога Skill
+
+```
+my-skill/
+├── SKILL.cat.md          # Required: metadata + prompt (entry file)
+├── scripts/              # Optional: SkillScript tool scripts
+│   ├── search.js
+│   └── export.js
+└── references/           # Optional: reference material files
+    ├── api-docs.md
+    └── examples.json
+```
+
+> `SKILL.cat.md` — входной файл Skill. При установке по URL ScriptCat сначала загружает этот файл, затем по относительным путям загружает остальные файлы на основе `scripts` и `references`, объявленных во frontmatter.
+
+## Формат SKILL.cat.md
+
+SKILL.cat.md использует YAML frontmatter для объявления метаданных, а Markdown-тело служит промптом для AI.
+
+```markdown
+---
+name: "weather-assistant"
+description: "Weather lookup assistant, supports global city weather queries and forecasts"
+config:
+  apiKey:
+    title: "OpenWeather API Key"
+    type: "text"
+    secret: true
+    required: true
+  unit:
+    title: "Temperature unit"
+    type: "select"
+    values: ["celsius", "fahrenheit"]
+    default: "celsius"
+  detailed:
+    title: "Detailed mode"
+    type: "switch"
+    default: false
+  maxDays:
+    title: "Forecast days"
+    type: "number"
+    default: 7
+---
+
+# Weather Lookup Assistant
+
+You can use the following tools to look up weather information:
+
+## Tool Description
+
+- **get_weather**: looks up the current weather and forecast for a given city
+  - the `city` parameter is the city name (Chinese and English both supported)
+  - the `days` parameter is the number of forecast days
+
+## Usage Rules
+
+1. When the user asks about the weather, first confirm the city name
+2. By default, return the current weather plus a 3-day forecast
+3. Display temperature according to the configured unit
+```
+
+### Поля метаданных
+
+| Поле | Тип | Обязательно | Описание |
+|------|------|------|------|
+| `name` | `string` | Да | Уникальный идентификатор Skill (рекомендуется английский kebab-case) |
+| `description` | `string` | Да | Краткое описание (показывается в списке) |
+| `version` | `string` | Нет | Номер версии (формат semver, например `1.0.0`), используется для проверки обновлений |
+| `scripts` | `string[]` | Нет | Список имён файлов скриптов (например, `["search.js"]`); при установке по URL автоматически загружаются из каталога `scripts/` |
+| `references` | `string[]` | Нет | Список имён файлов справочных материалов (например, `["api-docs.md"]`); при установке по URL автоматически загружаются из каталога `references/` |
+| `config` | `object` | Нет | Определения полей конфигурации |
+
+### Типы полей конфигурации
+
+| type | Описание | Особые свойства |
+|------|------|---------|
+| `text` | Текстовый ввод | `secret`: маскируется ли в UI |
+| `number` | Числовой ввод | — |
+| `select` | Выпадающий список | `values`: список вариантов (`string[]`) |
+| `switch` | Переключатель | — |
+
+**Общие свойства:**
+
+| Свойство | Тип | Описание |
+|------|------|------|
+| `title` | `string` | Отображаемый заголовок |
+| `required` | `boolean` | Обязательность |
+| `default` | `unknown` | Значение по умолчанию |
+| `secret` | `boolean` | Конфиденциальная информация |
+
+Пользователь заполняет значения конфигурации в настройках Skill на панели управления.
+
+### Тело промпта
+
+Markdown-тело внедряется как системный промпт AI. Рекомендации по написанию:
+
+- Опишите инструменты, которые предоставляет Skill, и их назначение
+- Объясните смысл параметров каждого инструмента и правила использования
+- Приведите типичные сценарии и на что обратить внимание
+- Если есть справочные материалы, объясните, как к ним обращаться
+
+## Скрипты инструментов SkillScript
+
+SkillScript — скрипт инструмента, который AI может вызывать. Каждый файл SkillScript регистрируется как один инструмент LLM.
+
+### Формат метаданных
+
+```javascript
+// ==SkillScript==
+// @name        get_weather
+// @description Look up the weather for a given city
+// @param       city string [required] City name, Chinese and English both supported
+// @param       days number Number of forecast days, defaults to 3
+// @param       format string [json,text] Output format
+// @grant       CAT.agent.opfs
+// @require     https://cdn.example.com/utils.js
+// @timeout     60
+// ==SkillScript==
+```
+
+### Поля метаданных
+
+| Тег | Описание | Пример |
+|------|------|------|
+| `@name` | Имя инструмента (используется при вызове AI) | `get_weather` |
+| `@description` | Описание инструмента (AI решает, когда его вызывать) | `Look up city weather` |
+| `@param` | Определение параметра (можно повторять) | см. ниже |
+| `@grant` | Нужное разрешение GM API | `CAT.agent.opfs` |
+| `@require` | URL внешней библиотеки (кэшируется после загрузки) | `https://cdn.example.com/lib.js` |
+| `@timeout` | Таймаут выполнения в секундах | `60` (по умолчанию 300) |
+
+### Синтаксис `@param`
+
+```
+@param paramName type[enumValues] [required] description
+```
+
+**Тип:** `string`, `number`, `boolean`
+
+**Значения перечисления (необязательно):** в квадратных скобках, через запятую
+
+**Маркер обязательности:** добавьте `[required]` перед описанием
+
+```javascript
+// A required string parameter
+// @param city string [required] City name
+
+// A string parameter with an enum
+// @param unit string [celsius,fahrenheit] Temperature unit
+
+// An optional number parameter
+// @param days number Number of forecast days
+
+// A boolean parameter
+// @param detailed boolean Whether to return detailed information
+```
+
+Определения параметров автоматически преобразуются в JSON Schema для LLM при вызове инструмента.
+
+### Написание скрипта
+
+```javascript
+// ==SkillScript==
+// @name        get_weather
+// @description Look up the weather for a given city
+// @param       city string [required] City name
+// @param       days number Number of forecast days
+// @timeout     30
+// ==SkillScript==
+
+// 1. Receive the parameters passed in by the AI via arguments[0]
+const { city, days = 3 } = arguments[0];
+
+// 2. CAT_CONFIG provides the Skill config the user filled in on the dashboard
+const apiKey = CAT_CONFIG.apiKey;
+const unit = CAT_CONFIG.unit || "celsius";
+
+// 3. Run the business logic
+const url = `https://api.openweathermap.org/data/2.5/forecast?q=${city}&cnt=${days}&units=${unit === "celsius" ? "metric" : "imperial"}&appid=${apiKey}`;
+const response = await fetch(url);
+
+if (!response.ok) {
+  throw new Error(`API request failed: ${response.status}`);
+}
+
+const data = await response.json();
+
+// 4. Use return to send the result back to the AI
+return {
+  city: data.city.name,
+  country: data.city.country,
+  forecasts: data.list.map(item => ({
+    date: item.dt_txt,
+    temp: item.main.temp,
+    description: item.weather[0].description
+  }))
+};
+```
+
+### Окружение выполнения
+
+| Особенность | Описание |
+|------|------|
+| **Где выполняется** | Изолированная среда песочницы (без доступа к DOM) |
+| **Получение параметров** | `arguments[0]` — объект параметров, переданный AI |
+| **Получение конфигурации** | `CAT_CONFIG` — глобальный объект только для чтения с конфигурацией пользователя |
+| **Возвращаемое значение** | Оператор `return` возвращает JSON-сериализуемое значение |
+| **Асинхронность** | Поддерживаются `async/await`, `fetch`, `Promise` |
+| **Внешние библиотеки** | Загружаются через `@require`, кэшируются локально |
+| **Таймаут** | По умолчанию 300 секунд, настраивается через `@timeout` |
+| **GM API** | Доступны после объявления через `@grant` (например, `CAT.agent.opfs`) |
+
+### Внешние библиотеки `@require`
+
+```javascript
+// ==SkillScript==
+// @name        analyze
+// @description Data analysis
+// @require     https://cdn.jsdelivr.net/npm/lodash@4/lodash.min.js
+// ==SkillScript==
+
+// Libraries loaded via @require can be used directly
+const result = _.groupBy(data, "category");
+return result;
+```
+
+Внешние библиотеки кэшируются при первой загрузке; при последующих выполнениях используется кэш.
+
+## Справочные материалы
+
+Файлы в каталоге `references/` служат справочными материалами, к которым AI может обращаться. При необходимости AI читает эти файлы через встроенный инструмент `read_reference`.
+
+Хорошие кандидаты для справочных материалов:
+- Документация API
+- Описания форматов данных
+- Подборки примеров использования
+- Документы предметных знаний
+
+## Репозиторий примеров
+
+Мы поддерживаем официальный репозиторий примеров Skill с несколькими готовыми Skills и примерами script API:
+
+**[scriptscat/skills](https://github.com/scriptscat/skills)**
+
+**Список Skills:**
+
+| Каталог | Описание | Установка |
+|------|------|------|
+| `browser-automation/` | Анализ страниц, операции DOM, заполнение форм, скриншоты, навигация | [Установить](https://raw.githubusercontent.com/scriptscat/skills/main/browser-automation/SKILL.cat.md) |
+| `scheduled-tasks/` | Задачи по расписанию (внутренний + режим событий) | [Установить](https://raw.githubusercontent.com/scriptscat/skills/main/scheduled-tasks/SKILL.cat.md) |
+| `skill-creator/` | Помогает создавать, тестировать и упаковывать новые Skills | [Установить](https://raw.githubusercontent.com/scriptscat/skills/main/skill-creator/SKILL.cat.md) |
+| `file-parser/` | Разбор распространённых форматов файлов (Excel, PDF, Word, CSV, PPT) | [Установить](https://raw.githubusercontent.com/scriptscat/skills/main/file-parser/SKILL.cat.md) |
+| `scriptcat-dev/` | Помощник разработки скриптов ScriptCat/Tampermonkey | [Установить](https://raw.githubusercontent.com/scriptscat/skills/main/scriptcat-dev/SKILL.cat.md) |
+| `synology-office-sheet/` | Чтение/запись таблиц Synology Office | [Установить](https://raw.githubusercontent.com/scriptscat/skills/main/synology-office-sheet/SKILL.cat.md) |
+| `wechat-publisher/` | Помощник по работе с официальным аккаунтом WeChat — сбор контента, написание и публикация статей | [Установить](https://raw.githubusercontent.com/scriptscat/skills/main/wechat-publisher/SKILL.cat.md) |
+| `xiaohongshu-publisher/` | Помощник по работе с Xiaohongshu (RED) — написание постов, генерация изображений и публикация | [Установить](https://raw.githubusercontent.com/scriptscat/skills/main/xiaohongshu-publisher/SKILL.cat.md) |
+
+**Примеры кода:**
+
+| Каталог | Описание |
+|------|------|
+| `examples/conversation/` | Примеры Conversation API — чат, потоки, вызовы инструментов |
+| `examples/dom/` | Примеры DOM API — чтение страниц, заполнение форм, управление вкладками |
+| `examples/config/` | Примеры Skill Config — объявление полей конфигурации и использование `CAT_CONFIG` |
+| `examples/page_copilot.user.js` | Полный пример пользовательского скрипта — AI-помощник по правому клику с потоковым UI |
+
+Рекомендуется начинать изучение разработки Skill с кода в репозитории примеров.
+
+## Способы установки
+
+### Установка по URL
+
+Откройте URL `SKILL.cat.md` прямо в браузере; ScriptCat автоматически перехватит его и покажет страницу установки.
+
+Также можно сделать это из панели управления → Agent → Управление Skill:
+
+1. Нажмите кнопку установки по URL
+2. Вставьте URL `SKILL.cat.md`
+3. Подтвердите установку
+
+ScriptCat сначала загружает `SKILL.cat.md`, затем по относительным путям — остальные файлы на основе `scripts` и `references` во frontmatter. После установки сохраняется `installUrl`, который позже используется для проверки обновлений по номеру версии.
+
+### Установка из скрипта
+
+```javascript
+// ==UserScript==
+// @grant CAT.agent.skills
+// ==/UserScript==
+
+await CAT.agent.skills.install(
+  skillMdContent,
+  [{ name: "search.js", code: scriptCode }],
+  [{ name: "docs.md", content: docsContent }]
+);
+```
+
+## Механизм загрузки Skill
+
+Skills используют трёхуровневый прогрессивный механизм загрузки для оптимизации использования контекста:
+
+| Уровень | Когда | Содержимое |
+|------|------|------|
+| **Summary** | В начале диалога | Имя Skill + описание + список инструментов (внедряется в системный промпт) |
+| **Prompt** | Когда AI активно вызывает `load_skill` | Полное тело SKILL.cat.md |
+| **Tools** | После load_skill | SkillScripts регистрируются как вызываемые инструменты LLM |
+
+AI автоматически вызывает `load_skill`, когда нужно загрузить полное содержимое Skill и инструменты.
+
+## Полный пример
+
+### Структура каталога
+
+```
+translator-skill/
+├── SKILL.cat.md
+├── scripts/
+│   └── translate.js
+└── references/
+    └── language-codes.md
+```
+
+### SKILL.cat.md
+
+```markdown
+---
+name: "translator"
+description: "Multi-language translation tool, supports 100+ languages"
+version: "1.0.0"
+scripts:
+  - translate.js
+references:
+  - language-codes.md
+config:
+  apiKey:
+    title: "Translation API Key"
+    type: "text"
+    secret: true
+    required: true
+  defaultTarget:
+    title: "Default target language"
+    type: "select"
+    values: ["zh", "en", "ja", "ko", "fr", "de", "es"]
+    default: "zh"
+---
+
+# Translation Assistant
+
+Use the `translate` tool to translate text. Consult language-codes.md for the full list of language codes.
+
+## Usage Rules
+
+- If the user hasn't specified a target language, use the default language from the config
+- Automatically split long text into chunks for translation
+- Preserve the original formatting (Markdown, code blocks, etc.)
+```
+
+### scripts/translate.js
+
+```javascript
+// ==SkillScript==
+// @name        translate
+// @description Translate text into a given language
+// @param       text string [required] The text to translate
+// @param       target string Target language code (defaults to the config value)
+// @param       source string Source language code (defaults to auto-detect)
+// @timeout     60
+// ==SkillScript==
+
+const { text, target, source } = arguments[0];
+const apiKey = CAT_CONFIG.apiKey;
+const targetLang = target || CAT_CONFIG.defaultTarget || "zh";
+
+const response = await fetch("https://api.example.com/translate", {
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+    "Authorization": `Bearer ${apiKey}`
+  },
+  body: JSON.stringify({
+    text,
+    target_language: targetLang,
+    source_language: source || "auto"
+  })
+});
+
+if (!response.ok) {
+  throw new Error(`Translation failed: ${response.statusText}`);
+}
+
+const result = await response.json();
+return {
+  original: text,
+  translated: result.translated_text,
+  source_language: result.detected_language,
+  target_language: targetLang
+};
+```
+
+### references/language-codes.md
+
+```markdown
+# Language Code Reference
+
+| Code | Language |
+|------|------|
+| zh | Chinese |
+| en | English |
+| ja | Japanese |
+| ko | Korean |
+| fr | French |
+| de | German |
+| es | Spanish |
+| ...  | ... |
+```
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-skill-install.md b/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-skill-install.md
new file mode 100644
index 00000000..6ca31cea
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-skill-install.md
@@ -0,0 +1,96 @@
+---
+title: Установка и использование Skills
+---
+
+Skill — пакет расширения для Agent, который внедряет предметные знания и пользовательские инструменты в AI. На этой странице описано, как устанавливать, настраивать и управлять Skills.
+
+:::tip Официальный репозиторий Skill
+**[scriptscat/skills](https://github.com/scriptscat/skills)** — готовые Skills для автоматизации браузера, задач по расписанию, разбора файлов, помощника разработки скриптов и многого другого.
+:::
+
+## Способы установки
+
+### Способ 1: установка по URL
+
+Откройте URL `SKILL.cat.md` прямо в адресной строке браузера; ScriptCat автоматически перехватит его и покажет страницу подтверждения установки.
+
+Например, установка официального Skill browser-automation:
+
+```
+https://raw.githubusercontent.com/scriptscat/skills/main/browser-automation/SKILL.cat.md
+```
+
+Также можно сделать это из панели управления:
+
+1. Откройте панель ScriptCat → **Agent → Skills**
+2. Нажмите кнопку **URL** в правом верхнем углу
+3. Вставьте URL `SKILL.cat.md`
+4. Нажмите «Установить»
+
+ScriptCat автоматически загрузит `SKILL.cat.md` вместе с объявленными в нём скриптами и справочными файлами.
+
+### Способ 2: установка через ZIP
+
+1. Откройте панель ScriptCat → **Agent → Skills**
+2. Нажмите кнопку **+** в правом верхнем углу
+3. Выберите пакет Skill в формате `.zip`
+
+Структура каталогов ZIP-пакета должна соответствовать стандартному формату Skill (содержать `SKILL.cat.md`).
+
+## Список официальных Skills
+
+Также можно щёлкнуть правой кнопкой `Copy Link` и вставить ссылку в поле URL управления Skill для установки.
+
+| Skill | Описание | Установка |
+|-------|------|------|
+| [browser-automation](https://github.com/scriptscat/skills/tree/main/browser-automation) | Анализ страниц, операции DOM, заполнение форм, скриншоты, навигация | [Установить](https://raw.githubusercontent.com/scriptscat/skills/main/browser-automation/SKILL.cat.md) |
+| [scheduled-tasks](https://github.com/scriptscat/skills/tree/main/scheduled-tasks) | Задачи по расписанию (автовыполнение LLM / колбэки скриптов) | [Установить](https://raw.githubusercontent.com/scriptscat/skills/main/scheduled-tasks/SKILL.cat.md) |
+| [skill-creator](https://github.com/scriptscat/skills/tree/main/skill-creator) | Помогает создавать, тестировать и упаковывать новые Skills | [Установить](https://raw.githubusercontent.com/scriptscat/skills/main/skill-creator/SKILL.cat.md) |
+| [file-parser](https://github.com/scriptscat/skills/tree/main/file-parser) | Разбор файлов Excel, PDF, Word, CSV и PPT | [Установить](https://raw.githubusercontent.com/scriptscat/skills/main/file-parser/SKILL.cat.md) |
+| [scriptcat-dev](https://github.com/scriptscat/skills/tree/main/scriptcat-dev) | Помощник разработки скриптов ScriptCat/Tampermonkey | [Установить](https://raw.githubusercontent.com/scriptscat/skills/main/scriptcat-dev/SKILL.cat.md) |
+| [synology-office-sheet](https://github.com/scriptscat/skills/tree/main/synology-office-sheet) | Чтение/запись таблиц Synology Office | [Установить](https://raw.githubusercontent.com/scriptscat/skills/main/synology-office-sheet/SKILL.cat.md) |
+| [wechat-publisher](https://github.com/scriptscat/skills/tree/main/wechat-publisher) | Помощник по работе с официальным аккаунтом WeChat | [Установить](https://raw.githubusercontent.com/scriptscat/skills/main/wechat-publisher/SKILL.cat.md) |
+| [xiaohongshu-publisher](https://github.com/scriptscat/skills/tree/main/xiaohongshu-publisher) | Помощник по работе с Xiaohongshu (RED) | [Установить](https://raw.githubusercontent.com/scriptscat/skills/main/xiaohongshu-publisher/SKILL.cat.md) |
+
+## Настройка Skill
+
+Некоторым Skills нужна конфигурация (например, API Key):
+
+1. Найдите установленный Skill на странице **Agent → Skills**
+2. Нажмите значок **настроек** (шестерёнка)
+3. Заполните конфигурацию и сохраните
+
+Поля с меткой `secret` в конфигурации маскируются в UI.
+
+## Включение / отключение
+
+На странице управления Skills используйте переключатель на карточке Skill, чтобы управлять включением. Отключённые Skills не загружаются в диалоги.
+
+## Проверка обновлений
+
+Skills, установленные по URL, поддерживают проверку версий:
+
+1. Нажмите кнопку **Проверить обновления** в правом верхнем углу страницы Skills
+2. На карточке Skill с доступной новой версией появится кнопка **Обновить**
+3. Нажмите, чтобы обновить в один клик
+
+Обновления сравниваются по полю `version` (формат semver), объявленному в `SKILL.cat.md`.
+
+## Использование Skills в диалоге
+
+Установленные Skills автоматически доступны в диалогах Agent. AI сам решает, когда загружать и вызывать инструменты Skill, исходя из содержимого диалога.
+
+Также можно указать, какие Skills загружать, при создании диалога:
+
+```javascript
+const conv = await CAT.agent.conversation.create({
+  skills: "auto"              // automatically load all Skills
+  // or specify particular Skills
+  // skills: ["browser-automation", "file-parser"]
+});
+```
+
+## Узнать больше
+
+- [API управления Skill](./agent-skill.md) — управление Skills программно из скрипта
+- [Руководство по разработке Skill](./agent-skill-dev.md) — создание собственного Skill
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-skill.md b/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-skill.md
new file mode 100644
index 00000000..687328a7
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-skill.md
@@ -0,0 +1,122 @@
+---
+title: API управления Skill
+---
+
+`@grant CAT.agent.skills`
+
+API управления Skill позволяет скрипту запрашивать, устанавливать, удалять и вызывать пакеты Skill.
+
+О разработке и упаковке Skill см. [Руководство по разработке Skill](../agent-skill-dev). Официальный репозиторий примеров Skill: [scriptscat/skills](https://github.com/scriptscat/skills).
+
+## list — список установленных Skills
+
+```javascript
+const skills = await CAT.agent.skills.list();
+```
+
+**Возвращаемое значение, SkillSummary[]:**
+
+| Поле | Тип | Описание |
+|------|------|------|
+| `name` | `string` | Имя Skill |
+| `description` | `string` | Описание Skill |
+| `version` | `string` | Номер версии (semver) |
+| `toolNames` | `string[]` | Список имён инструментов SkillScript |
+| `referenceNames` | `string[]` | Список имён файлов справочных материалов |
+| `hasConfig` | `boolean` | Объявлены ли поля конфигурации |
+| `enabled` | `boolean` | Включён ли (по умолчанию `true`) |
+| `installUrl` | `string` | URL источника установки (для проверки обновлений) |
+| `installtime` | `number` | Временная метка установки |
+| `updatetime` | `number` | Временная метка обновления |
+
+## get — детали Skill
+
+```javascript
+const skill = await CAT.agent.skills.get(name);
+```
+
+Возвращает полный `SkillRecord` или `null`, если не существует.
+
+**Структура SkillRecord:**
+
+Наследует все поля `SkillSummary`, плюс:
+
+| Поле | Тип | Описание |
+|------|------|------|
+| `prompt` | `string` | Markdown-тело SKILL.cat.md (промпт для AI) |
+| `config` | `Record<string, SkillConfigField>` | Определения полей конфигурации (schema) |
+
+**Структура SkillConfigField:**
+
+| Поле | Тип | Описание |
+|------|------|------|
+| `title` | `string` | Отображаемый заголовок |
+| `type` | `"text" \| "number" \| "select" \| "switch"` | Тип поля |
+| `secret` | `boolean` | Конфиденциальная информация (маскируется в UI) |
+| `required` | `boolean` | Обязательность |
+| `default` | `unknown` | Значение по умолчанию |
+| `values` | `string[]` | Список вариантов (только для типа `select`) |
+
+## install — установить Skill
+
+```javascript
+const record = await CAT.agent.skills.install(skillMd, scripts?, references?);
+```
+
+**Параметры:**
+
+| Параметр | Тип | Описание |
+|------|------|------|
+| `skillMd` | `string` | Содержимое файла SKILL.cat.md (обязательно) |
+| `scripts` | `Array<{ name, code }>` | Список файлов SkillScript |
+| `references` | `Array<{ name, content }>` | Список файлов справочных материалов |
+
+Если Skill с таким именем уже существует, выполняется обновление.
+
+```javascript
+const record = await CAT.agent.skills.install(
+  `---
+name: my-search
+description: Custom search tool
+---
+
+When the user needs to search, use the search tool.`,
+  [{ name: "search.js", code: skillScriptCode }],
+  [{ name: "api-docs.md", content: "# API Documentation\n..." }]
+);
+```
+
+## remove — удалить Skill
+
+```javascript
+const success = await CAT.agent.skills.remove(name);
+```
+
+Возвращает `true` при успешном удалении, `false`, если Skill не существует.
+
+## call — прямой вызов SkillScript
+
+```javascript
+const result = await CAT.agent.skills.call(skillName, scriptName, params?);
+```
+
+Напрямую выполняет SkillScript из указанного Skill, минуя AI-диалог.
+
+**Параметры:**
+
+| Параметр | Тип | Описание |
+|------|------|------|
+| `skillName` | `string` | Имя Skill (обязательно) |
+| `scriptName` | `string` | Имя SkillScript (обязательно) |
+| `params` | `Record<string, unknown>` | Передаваемые параметры (соответствуют объявлениям `@param`) |
+
+```javascript
+// Directly call a search script from a Skill
+const results = await CAT.agent.skills.call(
+  "my-search",
+  "search",
+  { query: "ScriptCat", limit: 5 }
+);
+```
+
+> Выполнение SkillScript ограничено таймаутом (по умолчанию 300 секунд, настраивается через `@timeout`).
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-task.md b/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-task.md
new file mode 100644
index 00000000..c9323e10
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-task.md
@@ -0,0 +1,197 @@
+---
+title: API задач по расписанию
+---
+
+`@grant CAT.agent.task`
+
+API задач по расписанию позволяет скрипту создавать задачи на основе Cron-выражений с поддержкой двух режимов выполнения.
+
+## Режимы выполнения
+
+### Внутренний режим (Internal)
+
+Автоматически выполняется системой Agent:
+- При срабатывании cron автоматически создаёт или возобновляет диалог
+- Отправляет настроенный `prompt` в LLM
+- Позволяет указать модель и Skills
+- История выполнения и использование токенов записываются автоматически
+
+### Режим событий (Event)
+
+Обрабатывается самим скриптом:
+- При срабатывании cron скрипту отправляется уведомление о событии
+- Скрипт слушает событие через `addListener`
+- Полностью пользовательская логика обработки
+
+## create — создать задачу
+
+```javascript
+const task = await CAT.agent.task.create(options);
+```
+
+**Параметры, AgentTaskCreateOptions:**
+
+| Параметр | Тип | Обязательно | Описание |
+|------|------|------|------|
+| `name` | `string` | Да | Имя задачи |
+| `crontab` | `string` | Да | Стандартное cron-выражение (5 полей: minute hour day month weekday) |
+| `mode` | `"internal" \| "event"` | Да | Режим выполнения |
+| `enabled` | `boolean` | Нет | Включена ли; по умолчанию `true` |
+| `notify` | `boolean` | Нет | Отправлять ли уведомление браузера при срабатывании |
+| `prompt` | `string` | Нет | Промпт для внутреннего режима |
+| `modelId` | `string` | Нет | ID модели для внутреннего режима |
+| `skills` | `string[]` | Нет | Список Skills для загрузки во внутреннем режиме |
+| `maxIterations` | `number` | Нет | Максимум раундов вызовов инструментов во внутреннем режиме; по умолчанию `10` |
+
+**Возвращаемое значение, AgentTask:**
+
+| Поле | Тип | Описание |
+|------|------|------|
+| `id` | `string` | ID задачи |
+| `name` | `string` | Имя задачи |
+| `crontab` | `string` | Cron-выражение |
+| `mode` | `string` | Режим выполнения |
+| `enabled` | `boolean` | Включена ли |
+| `notify` | `boolean` | Отправляются ли уведомления |
+| `nextruntime` | `number` | Временная метка следующего выполнения |
+| `lastruntime` | `number` | Временная метка последнего выполнения |
+| `lastRunStatus` | `"success" \| "error"` | Статус последнего выполнения |
+| `lastRunError` | `string` | Сообщение об ошибке последнего выполнения |
+| `createtime` | `number` | Временная метка создания |
+
+**Примеры cron-выражений:**
+
+| Выражение | Описание |
+|--------|------|
+| `* * * * *` | Каждую минуту |
+| `0 9 * * *` | Каждый день в 09:00 |
+| `0 */2 * * *` | Каждые 2 часа |
+| `30 8 * * 1-5` | По будням в 08:30 |
+| `0 0 1 * *` | 1-го числа каждого месяца в 00:00 |
+
+## list — список всех задач
+
+```javascript
+const tasks = await CAT.agent.task.list();
+```
+
+Возвращает все задачи, созданные текущим скриптом.
+
+## get — детали задачи
+
+```javascript
+const task = await CAT.agent.task.get(taskId);
+```
+
+Возвращает `undefined`, если задача не существует.
+
+## update — обновить задачу
+
+```javascript
+const task = await CAT.agent.task.update(taskId, partial);
+```
+
+**Обновляемые поля:**
+
+```javascript
+await CAT.agent.task.update(task.id, {
+  name: "New name",
+  crontab: "0 10 * * *",
+  enabled: false,
+  prompt: "New prompt",
+  notify: true
+});
+```
+
+После обновления `nextruntime` пересчитывается автоматически.
+
+## remove — удалить задачу
+
+```javascript
+const success = await CAT.agent.task.remove(taskId);
+```
+
+## runNow — запустить немедленно
+
+```javascript
+await CAT.agent.task.runNow(taskId);
+```
+
+Сразу запускает одно выполнение задачи, не дожидаясь cron-расписания (неблокирующе, в фоне).
+
+## addListener — слушать срабатывания задачи
+
+```javascript
+const listenerId = await CAT.agent.task.addListener(taskId, callback);
+```
+
+Используется только для задач в **режиме событий**. Запускает callback при срабатывании cron.
+
+**Параметр callback, AgentTaskTrigger:**
+
+| Поле | Тип | Описание |
+|------|------|------|
+| `taskId` | `string` | ID задачи |
+| `name` | `string` | Имя задачи |
+| `crontab` | `string` | Cron-выражение |
+| `triggeredAt` | `number` | Временная метка срабатывания |
+
+## removeListener — удалить слушатель
+
+```javascript
+await CAT.agent.task.removeListener(listenerId);
+```
+
+## Полные примеры
+
+### Внутренний режим — автоматическое выполнение AI
+
+```javascript
+// ==UserScript==
+// @name        Daily News Summary
+// @match       *://*/*
+// @grant       CAT.agent.task
+// ==/UserScript==
+
+const task = await CAT.agent.task.create({
+  name: "Daily news summary",
+  crontab: "0 9 * * *",       // every day at 9:00
+  mode: "internal",
+  prompt: "Please search today's tech news and generate a short summary saved to OPFS",
+  skills: ["web-search"],
+  maxIterations: 10,
+  notify: true
+});
+
+console.log("Task created, next run:", new Date(task.nextruntime));
+```
+
+### Режим событий — обработку делает скрипт
+
+```javascript
+// ==UserScript==
+// @name        Scheduled Data Collection
+// @match       *://*/*
+// @grant       CAT.agent.task
+// @grant       CAT.agent.dom
+// ==/UserScript==
+
+const task = await CAT.agent.task.create({
+  name: "Stock data collection",
+  crontab: "*/30 9-15 * * 1-5", // every 30 minutes, 9:00-15:00 on weekdays
+  mode: "event",
+  enabled: true,
+  notify: false
+});
+
+await CAT.agent.task.addListener(task.id, async (trigger) => {
+  console.log(`Task triggered: ${trigger.name} at ${new Date(trigger.triggeredAt)}`);
+
+  // custom collection logic
+  await CAT.agent.dom.navigate("https://finance.example.com/stock");
+  const content = await CAT.agent.dom.readPage({ selector: ".stock-table" });
+
+  // process the data...
+  console.log("Collection complete");
+});
+```
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/index.md b/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/index.md
new file mode 100644
index 00000000..41bc72a9
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/index.md
@@ -0,0 +1,104 @@
+---
+title: Agent
+---
+
+:::caution Фаза тестирования
+Функция Agent пока находится в фазе тестирования; перечисленные ниже API и поведение могут измениться до официального релиза.
+:::
+
+## Обзор
+
+ScriptCat v1.4 представляет систему Agent, дающую пользовательским скриптам набор возможностей: AI-диалоги, автоматизация браузера, управление файлами и задачи по расписанию.
+
+Скрипты вызывают эти возможности через пространство имён `CAT.agent.*`, и для каждого API нужно объявить соответствующее разрешение через `@grant`.
+
+## Модули функций
+
+| Модуль | Разрешение | Описание |
+|------|---------|------|
+| [Диалог](./agent-conversation) | `@grant CAT.agent.conversation` | Создание AI-диалогов, отправка сообщений, потоковые ответы, пользовательские инструменты |
+| [Операции DOM](./agent-dom) | `@grant CAT.agent.dom` | Навигация по страницам, скриншоты, клики, заполнение, прокрутка, мониторинг DOM |
+| [Skill](./agent-skill) | `@grant CAT.agent.skills` | Установка/удаление/вызов пакетов Skill |
+| [Задачи по расписанию](./agent-task) | `@grant CAT.agent.task` | Задачи по расписанию, прослушивание событий |
+| [Модель](./agent-model) | `@grant CAT.agent.model` | Запрос информации о настроенных моделях (только чтение) |
+| [Файлы OPFS](./agent-opfs) | `@grant CAT.agent.opfs` | Чтение/запись файлов рабочего пространства Agent |
+| [MCP](./agent-mcp) | `@grant CAT.agent.mcp` | Управление подключениями MCP-серверов |
+| [Разработка Skill](./agent-skill-dev) | — | Руководство по разработке SKILL.cat.md + SkillScript |
+
+## Быстрый старт
+
+Простейший возможный скрипт Agent:
+
+```javascript
+// ==UserScript==
+// @name        Hello Agent
+// @match       *://*/*
+// @grant       CAT.agent.conversation
+// ==/UserScript==
+
+const conv = await CAT.agent.conversation.create();
+const reply = await conv.chat("Hi, please introduce yourself");
+console.log(reply.content);
+```
+
+## Обзор архитектуры
+
+Система Agent охватывает несколько изолированных контекстов внутри расширения браузера:
+
+```
+User script → Sandbox (isolated execution)
+              ↓ WindowMessage
+           Offscreen (DOM access)
+              ↓ ExtensionMessage
+           Service Worker (core scheduling)
+              ├── LLM Provider (OpenAI / Anthropic)
+              ├── ToolRegistry (tool registration and execution)
+              ├── SkillScriptExecutor (Skill script execution)
+              ├── MCPClient (MCP protocol client)
+              └── TaskScheduler (scheduled task scheduling)
+```
+
+### Структура хранения
+
+Agent хранит данные с помощью OPFS браузера (Origin Private File System):
+
+```
+agents/
+├── conversations/       # conversation history
+├── attachments/         # attachments (images, files)
+├── skills/{name}/       # Skill package files
+│   ├── SKILL.cat.md
+│   ├── scripts/
+│   └── references/
+├── tasks/               # scheduled task config and execution records
+└── workspace/           # user workspace files (the directory opfs_* tools operate on)
+```
+
+### Поддерживаемые модели
+
+| Провайдер | Формат | Возможности |
+|----------|------|------|
+| OpenAI-compatible | OpenAI Chat Completions API | Поддержка GPT-4o, DeepSeek и других совместимых моделей |
+| Anthropic | Anthropic Messages API | Поддержка семейства Claude, Prompt Caching |
+| Zhipu | Zhipu API | Поддержка семейства моделей GLM |
+
+Добавьте Provider и API Key в разделе «Конфигурация моделей» панели управления, чтобы использовать их.
+
+### Экосистема Skill
+
+Skill — пакет, объединяющий промпты + скрипты инструментов + справочные материалы, позволяющий внедрять в Agent предметные знания и пользовательские инструменты.
+
+**Официальный репозиторий Skill: [scriptscat/skills](https://github.com/scriptscat/skills)**
+
+Включает готовые Skills для автоматизации браузера, задач по расписанию, инструмента создания Skill, примеров conversation/DOM/config и многого другого.
+
+**Способы установки:**
+
+- **Установка по URL** — откройте URL `SKILL.cat.md` прямо в браузере; ScriptCat автоматически перехватит его и покажет страницу установки. Также можно вставить URL в панели управления: Agent → Управление Skill.
+- **Установка из скрипта** — программная установка через API `CAT.agent.skills.install()`
+
+**Проверка обновлений:**
+
+Skill, установленный по URL, сохраняет источник установки; панель управления позволяет проверять обновления и обновлять в один клик (на основе semver-сравнения поля `version`).
+
+Подробности: [API управления Skill](./agent-skill) и [Руководство по разработке Skill](./agent-skill-dev).
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/dev/api.md b/i18n/ru/docusaurus-plugin-content-docs/current/dev/api.md
new file mode 100644
index 00000000..94190cd0
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/dev/api.md
@@ -0,0 +1,635 @@
+---
+title: Документация API
+---
+
+## Обзор
+
+Определения API этого расширения основаны на [документации Tampermonkey](https://www.tampermonkey.net/documentation.php). Из‑за ограничений по времени и ресурсам пока реализована только часть API, и она продолжит развиваться. Любой API, который это расширение расширяет или который отличается от исходного GM API, специально отмечен в документации (символом `*`). Для некоторых API также предоставляется синхронный/promise-вариант по правилу `GM.*` — подробности см. в содержании документации.
+
+Подробные определения API смотрите в `scriptcat.d.ts` или во встроенных подсказках редактора — документация может быть не всегда актуальной. API, специфичные для этого расширения, описаны в [документации CatApi](cat-api.md).
+
+Связанные примеры также можно найти в [каталоге example](https://github.com/scriptscat/scriptcat/tree/main/example).
+
+## Определения
+
+### GM_info
+
+Получает информацию о скрипте, включая метаданные и параметры среды выполнения. Часто используемые поля: `scriptHandler`, `version`, `scriptMetaStr`, `scriptUpdateURL`, `downloadMode` и другие. Подробное (хотя и не исчерпывающее) определение см. в `scriptcat.d.ts`.
+
+```js
+console.log(GM_info.scriptHandler);
+console.log(GM_info.version);
+console.log(GM_info.scriptMetaStr);
+```
+
+* `sandboxMode` сейчас имеет только значение `raw`. `runAt` не поддерживается. `userAgentData` поддерживается, но может не полностью совпадать с Tampermonkey.
+
+### GM_log \*
+
+Функция логирования. Журналы фонового скрипта можно просмотреть в журнале запусков панели управления (щелчок по столбцу статуса выполнения). По сравнению с Tampermonkey добавлен уровень лога `level`.
+
+```typescript
+declare function GM_log(message: string, level?: GMTypes.LoggerLevel): void;
+
+declare namespace GMTypes {
+  type LoggerLevel = "debug" | "info" | "warn" | "error";
+}
+```
+
+```js
+GM_log("debug info", "debug");
+```
+
+### GM_get/set/deleteValue
+
+Получает или задаёт значение в хранилище. Данные с одним и тем же [**storageName**](meta.md#storagename-) могут совместно использоваться и синхронизироваться в реальном времени.
+
+```typescript
+// Add data — note that data can only be one of bool/string/number/object; you cannot store a class instance
+declare function GM_setValue(name: string, value: any): void;
+// Get data
+declare function GM_getValue(name: string, defaultValue?: any): any | undefined;
+// Delete data; getting it again returns undefined or defaultValue
+declare function GM_deleteValue(name: string): void;
+```
+
+```js
+GM_setValue("foo", 42);
+const v = GM_getValue("foo", 0);
+GM_deleteValue("foo");
+```
+
+#### Примечание: при вызове `GM_setValue` с `undefined` ScriptCat удаляет этот ключ, в отличие от Tampermonkey/GreaseMonkey, которые сохраняют `undefined` как значение.
+
+#### Примечание: поскольку операции с данными асинхронны, вызов `window.close()` сразу после `GM_setValue` или `GM_deleteValue` может помешать корректному обновлению данных. Рекомендуется использовать `await GM.setValue` или `await GM.deleteValue`, чтобы дождаться завершения операции.
+
+### GM_listValues
+
+Возвращает список всех ключей.
+
+```typescript
+declare function GM_listValues(): string[];
+```
+
+```js
+console.log(GM_listValues());
+```
+
+### GM_setValues / GM_getValues / GM_deleteValues \*
+
+Пакетные API get/set (расширение).
+
+```typescript
+// Sets multiple values; values is an object whose keys are the value names and whose values are the value contents
+declare function GM_setValues(values: { [key: string]: any }): void;
+// Gets multiple values; if keysOrDefaults is an object, its values are used as the defaults
+declare function GM_getValues(keysOrDefaults: { [key: string]: any } | string[] | null | undefined): { [key: string]: any };
+// Deletes multiple values; names is an array of strings
+declare function GM_deleteValues(names: string[]): void;
+```
+
+```js
+// Batch set
+GM_setValues({ a: 1, b: 2 });
+// Batch get (returns the default if not present)
+const { a, b, c = 3 } = GM_getValues({ a: 0, b: 0, c: 3 });
+// Batch delete
+GM_deleteValues(["a", "b"]);
+```
+
+#### Примечание: поскольку операции с данными асинхронны, вызов `window.close()` сразу после `GM_setValues` или `GM_deleteValues` может помешать корректному обновлению данных. Рекомендуется использовать `await GM.setValues` или `await GM.deleteValues`, чтобы дождаться завершения операции.
+
+### GM_add/removeValueChangeListener
+
+> `tabid` удалён после 0.17.0-alpha — подробности см. в [GM_cookie](#gm_cookie-).
+
+Слушает изменения значения. `add` возвращает id слушателя, `remove` отменяет его. Этот метод можно использовать для простой коммуникации; с помощью [**storageName**](meta.md#storagename-) возможна межскриптовая коммуникация.
+
+```typescript
+// tabid is only present when listening from a background script
+type ValueChangeListener = (
+  name: string,
+  oldValue: any,
+  newValue: any,
+  remote: boolean,
+  tabid?: number
+) => any;
+
+declare function GM_addValueChangeListener(
+  name: string,
+  listener: GMTypes.ValueChangeListener
+): number;
+
+declare function GM_removeValueChangeListener(listenerId: number): void;
+```
+
+```js
+const id = GM_addValueChangeListener("foo", (k, oldV, newV, remote) => {
+  console.log(k, oldV, newV, remote);
+});
+GM_removeValueChangeListener(id);
+```
+
+### GM_getResourceText/GM_getResourceURL
+
+Получает информацию о ресурсе, объявленном через `@resource`.
+
+```typescript
+// GM_getResourceText gets the resource's text data; byte-type data such as images returns an empty string — use GM_getResourceURL for those instead
+declare function GM_getResourceText(name: string): string | undefined;
+// GM_getResourceURL gets base64-encoded data; a blob URL can also be obtained via the second parameter
+declare function GM_getResourceURL(name: string, isBlobUrl?: boolean): string | undefined;
+```
+
+```js
+const css = GM_getResourceText("mystyle");
+const imgUrl = GM_getResourceURL("logo");
+```
+
+### GM_addElement
+
+Вставляет элемент на страницу. Может обходить ограничения CSP.
+
+```typescript
+declare function GM_addElement(tag: string, attributes: any): HTMLElement;
+declare function GM_addElement(parentNode: Element, tag: string, attrs: any): HTMLElement;
+```
+
+```js
+// Insert a script
+GM_addElement("script", { src: "https://example.com/app.js" });
+// Insert a style
+GM_addElement(document.head, "style", { textContent: ".foo{color:blue}" });
+```
+
+### GM_addStyle
+
+Добавляет стиль на страницу и возвращает DOM-узел стиля. Может обходить ограничения CSP.
+
+```typescript
+declare function GM_addStyle(css: string): HTMLElement;
+```
+
+```js
+GM_addStyle(`
+  body { background: #f0f0f0; }
+  .btn { color: red; }
+`);
+```
+
+### GM_openInTab \*
+
+Открывает новое окно.
+
+```typescript
+declare function GM_openInTab(url: string, options: GMTypes.OpenTabOptions): GMTypes.Tab;
+declare function GM_openInTab(url: string, loadInBackground: boolean): GMTypes.Tab;
+declare function GM_openInTab(url: string): GMTypes.Tab;
+
+declare namespace GMTypes {
+  interface OpenTabOptions {
+    /**
+     * Determines whether the new tab gets focus when opened.
+     *
+     * - `true` → the new tab is immediately switched to the foreground.
+     * - `false` → the new tab opens in the background, without stealing focus from the current page.
+     *
+     * Default: true
+     */
+    active?: boolean;
+
+    /**
+     * Determines where the new tab is inserted.
+     *
+     * - If a `boolean`:
+     *   - `true` → inserted right after the current tab.
+     *   - `false` → inserted at the end of the window.
+     * - If a `number`:
+     *   - `0` → inserted one position before the current tab.
+     *   - `1` → inserted one position after the current tab.
+     *
+     * Default: true
+     */
+    insert?: boolean | number;
+
+    /**
+     * Determines whether the parent tab (i.e. `openerTabId`) is set.
+     *
+     * - `true` → the browser can track which tab opened the child tab,
+     *   which helps some extensions (like tab-tree managers) identify parent/child relationships.
+     *
+     * Default: true
+     */
+    setParent?: boolean;
+
+    /**
+     * Whether to open the tab in a private (incognito) window.
+     *
+     * Note: ScriptCat's manifest.json sets `"incognito": "split"`,
+     * so when running in a normal window, tabId/windowId will not be
+     * available, and only the "open a new tab" action can be performed.
+     *
+     * Default: false
+     */
+    incognito?: boolean;
+
+    /**
+     * Legacy compatibility field, supported only by Tampermonkey.
+     * Its meaning is the **opposite** of `active`:
+     *
+     * - `true` → equivalent to `active = false` (loads in the background).
+     * - `false` → equivalent to `active = true` (loads in the foreground).
+     *
+     * ⚠️ Not recommended: overlaps with `active` and is easy to confuse.
+     *
+     * Default: false
+     * @deprecated Use `active` instead
+     */
+    loadInBackground?: boolean;
+
+    /**
+     * Whether to pin the new tab to the left side of the browser's tab bar.
+     *
+     * - `true` → the new tab is pinned.
+     * - `false` → a regular tab.
+     *
+     * Default: false
+     */
+    pinned?: boolean;
+
+    /**
+     * Uses `window.open` to open the new tab instead of `chrome.tabs.create`.
+     * Useful when opening links with certain special protocols, e.g. `vscode://`, `m3u8dl://`.
+     * Other parameters have no effect when using this open method.
+     *
+     * Related: Issue #178 #1043
+     * Default: false
+     */
+    useOpen?: boolean;
+  }
+
+  interface Tab {
+    close(): void;
+    onclose?: () => void;
+    closed?: boolean;
+    name?: string;
+  }
+}
+```
+
+```js
+const tab = GM_openInTab("https://example.com", { active: false });
+tab.onclose = () => console.log("closed");
+tab.close();
+```
+
+### GM_get/saveTab/GM_getTabs
+
+Метод хранения данных, похожий на `GM_setValue`, но время жизни данных привязано к циклу открытия→закрытия одной вкладки браузера, и его нельзя использовать из фонового скрипта.
+
+```typescript
+// Get tab data
+declare function GM_getTab(callback: (obj: object) => void): void;
+// Save tab data
+declare function GM_saveTab(obj: object): void;
+// Get all tabs' data
+declare function GM_getTabs(callback: (objs: { [key: number]: object }) => void): void;
+```
+
+```js
+GM_saveTab({ foo: 1 }, () => console.log("saved"));
+GM_getTab(tab => console.log(tab));
+GM_getTabs(tabs => console.log(tabs));
+```
+
+### GM_registerMenuCommand *
+
+* Регистрирует пункт меню, отображаемый на popup-странице и в контекстном меню; при нажатии вызывается функция `listener`.
+* По умолчанию, как в Tampermonkey, пункты меню с одинаковым отображаемым текстом показываются только один раз.
+* Указание `id` позволяет обновлять пункт меню.
+* Если `name` — пустая строка и нет `listener`, в контекстное меню добавляется разделитель.
+
+```typescript
+function GM_registerMenuCommand(
+  name: string,
+  listener?: (inputValue?: any) => void,
+  options_or_accessKey?:
+    | {
+        id?: number | string;
+        accessKey?: string;
+        autoClose?: boolean; // ScriptCat-specific option; defaults to true, and false keeps the popup menu page open after clicking
+        nested?: boolean; // ScriptCat-specific option; defaults to true, and false raises the browser's right-click menu item from a third-level to a second-level menu
+        individual?: boolean; // ScriptCat-specific option; defaults to false, and true means identical menu items are not merged together
+      }
+    | string
+): number;
+```
+
+```js
+const cmdId = GM_registerMenuCommand("Test Command 01", () => alert("Called 01"));
+GM_registerMenuCommand("Test Command 02", () => alert("Called 02"), {id: "custom-id"});
+```
+
+### GM_unregisterMenuCommand
+
+Удаляет зарегистрированный пункт меню по его id.
+
+```typescript
+declare function GM_unregisterMenuCommand(id: number): void;
+```
+
+```js
+GM_unregisterMenuCommand(cmdId);
+GM_unregisterMenuCommand("custom-id");
+```
+
+### GM_notification \*
+
+Отправляет уведомление, предоставляя возможности `progress` и `buttons` (не поддерживается в Firefox), поэтому уведомление может показывать прогресс-бар или кнопки. Также есть два дополнительных метода: `GM_closeNotification` и `GM_updateNotification` (не поддерживаются в Firefox).
+
+[example](https://github.com/scriptscat/scriptcat/blob/main/example/gm_notification.js)
+
+```typescript
+declare function GM_notification(
+  details: GMTypes.NotificationDetails,
+  ondone?: GMTypes.NotificationOnDone
+): void;
+declare function GM_notification(
+  text: string,
+  title: string,
+  image: string,
+  onclick: GMTypes.NotificationOnClick
+): void;
+declare function GM_closeNotification(id: string): void;
+declare function GM_updateNotification(id: string, details: GMTypes.NotificationDetails): void;
+
+declare namespace GMTypes {
+  interface NotificationDetails {
+    text?: string;
+    title?: string;
+    tag?: string;
+    image?: string;
+    highlight?: boolean;
+    silent?: boolean;
+    timeout?: number;
+    url?: string;
+    onclick?: NotificationOnClick;
+    ondone?: NotificationOnDone;
+    progress?: number;
+    oncreate?: NotificationOnClick;
+    // At most 2 can exist
+    buttons?: NotificationButton[];
+  }
+
+  interface NotificationThis extends NotificationDetails {
+    id: string;
+  }
+
+  type NotificationOnClickEvent = {
+    event: "click" | "buttonClick";
+    id: string;
+    isButtonClick: boolean;
+    buttonClickIndex: number | undefined;
+    byUser: boolean | undefined;
+    preventDefault: () => void;
+    highlight: NotificationDetails["highlight"];
+    image: NotificationDetails["image"];
+    silent: NotificationDetails["silent"];
+    tag: NotificationDetails["tag"];
+    text: NotificationDetails["tag"];
+    timeout: NotificationDetails["timeout"];
+    title: NotificationDetails["title"];
+    url: NotificationDetails["url"];
+  };
+  type NotificationOnClick = (this: NotificationThis, event: NotificationOnClickEvent) => unknown;
+  type NotificationOnDone = (this: NotificationThis, user?: boolean) => unknown;
+
+  interface NotificationButton {
+    title: string;
+    iconUrl?: string;
+  }
+
+}
+
+```
+
+```js
+GM_notification({ title: "Progress", text: "Loading", progress: 50 });
+```
+
+#### Примечание: `GM_closeNotification` и `GM_updateNotification` специфичны для ScriptCat. Для обновления уведомления используйте `tag`.
+
+
+```js
+GM_notification({ title: "Progress", text: "Loading", progress: 50, tag: "notification01"});
+GM_notification({ title: "Progress", text: "Done", progress: 100, tag: "notification01"}); // updates the progress
+GM_notification({ title: "Progress", text: "Done", progress: 100, tag: "notification01", timeout: 1}); // closes after 1ms
+```
+
+### GM_setClipboard \*
+
+Записывает данные в буфер обмена. Обратный вызов пока не поддерживается, в отличие от Tampermonkey.
+
+```typescript
+declare function GM_setClipboard(
+  data: string,
+  info?: string | { type?: string; mimetype?: string }
+): void;
+```
+
+```js
+GM_setClipboard("Hello World", "text");
+```
+
+### GM_xmlhttpRequest \*
+
+* Кросс-доменный HTTP-запрос, который может обходить CSP, с поддержкой доменов, объявленных через `@connect`. Часть функциональности отсутствует; функция cookie сейчас не поддерживается в Firefox. Для доступа к хосту обычно требуется разрешение пользователя; если хост объявлен через `@connect`, отдельное подтверждение пользователя не запрашивается.
+
+* `anonymous` и `cookie` обрабатываются иначе, чем в Tampermonkey: когда `anonymous` равно true и задан `cookie`, отправляется только указанный cookie, без других cookie.
+
+* Также поддерживаются специальные заголовки:
+
+  - user-agent
+  - origin
+  - referer
+  - cookie
+  - host
+  - ...
+
+```typescript
+declare function GM_xmlhttpRequest(details: GMTypes.XHRDetails): GMTypes.AbortHandle<void>;
+
+declare namespace GMTypes {
+  interface XHRResponse {
+    finalUrl?: string;
+    readyState?: 0 | 1 | 2 | 3 | 4;
+    responseHeaders?: string;
+    status?: number;
+    statusText?: string;
+    response?: any;
+    responseText?: string;
+    responseXML?: Document | null;
+  }
+
+  interface XHRProgress extends XHRResponse {
+    done: number;
+    lengthComputable: boolean;
+    loaded: number;
+    position: number;
+    total: number;
+    totalSize: number;
+  }
+
+  type Listener<OBJ> = (event: OBJ) => any;
+
+  interface XHRDetails {
+    method?: "GET" | "HEAD" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS";
+    url: string;
+    headers?: { [key: string]: string };
+    data?: string | FormData;
+    cookie?: string;
+    binary?: boolean;
+    timeout?: number;
+    responseType?: "text" | "arraybuffer" | "blob" | "json" | "document" | "stream"; // stream is a fairly basic implementation in the current version
+    overrideMimeType?: string;
+    anonymous?: boolean;
+    fetch?: boolean;
+    user?: string;
+    password?: string;
+    nocache?: boolean;
+    redirect?: "follow" | "error" | "manual"; // to stay consistent with Tampermonkey, maxRedirects was deprecated after v0.17.0 in favor of redirect, which forces fetch mode
+    
+    onload?: Listener<XHRResponse>;
+    onloadstart?: Listener<XHRResponse>;
+    onloadend?: Listener<XHRResponse>;
+    onprogress?: Listener<XHRProgress>;
+    onreadystatechange?: Listener<XHRResponse>;
+    ontimeout?: () => void;
+    onabort?: () => void;
+    onerror?: (err: string) => void;
+  }
+}
+```
+
+```js
+GM_xmlhttpRequest({
+  method: "GET",
+  url: "https://api.example.com/data",
+  onload: res => console.log(res.responseText)
+});
+```
+
+### GM_download
+
+* Скачивает файл с настраиваемыми заголовками и другими опциями; по сравнению с Tampermonkey также поддерживает опции cookie и anonymous. При blob URL открывает загрузку напрямую и срабатывает только событие `onload` — это отличается от Tampermonkey и нужно для поддержки фоновых скриптов, которые иначе не могут создать загрузку (полезно, например, для генерации отчётов).
+* Возвращает объект Promise и предоставляет метод `abort()`.
+* В отличие от Tampermonkey, режим загрузки `native` в ScriptCat (по умолчанию) учитывает `@connect`: если хост URL загрузки не покрыт объявлениями `@connect` скрипта, ScriptCat запрашивает подтверждение пользователя; хосты из `@connect` скачиваются без запроса, а занесённые в чёрный список всегда отклоняются. Режим загрузки `browser` этой проверке не подчиняется. (В Tampermonkey `@connect` применяется только к `GM_xmlhttpRequest`, не к `GM_download`.)
+
+```typescript
+declare function GM_download(details: GMTypes.DownloadDetails): GMTypes.AbortHandle<boolean>;
+declare function GM_download(url: string, filename: string): GMTypes.AbortHandle<boolean>;
+
+declare namespace GMTypes {
+  interface DownloadError {
+    error:
+      | "not_enabled"
+      | "not_whitelisted"
+      | "not_permitted"
+      | "not_supported"
+      | "not_succeeded"
+      | "unknown";
+    details?: string;
+  }
+
+  interface DownloadDetails {
+    method?: "GET" | "POST";
+    downloadMode?: "native" | "browser";
+    url: string;
+    name: string;
+    headers?: { [key: string]: string };
+    saveAs?: boolean;
+    timeout?: number;
+    cookie?: string;
+    anonymous?: boolean;
+
+    onerror?: Listener<DownloadError>;
+    ontimeout?: () => void;
+    onload?: Listener<object>;
+    onprogress?: Listener<XHRProgress>;
+  }
+}
+```
+
+```js
+// Callback form
+const dl = GM_download({ url: "https://example.com/file.zip", name: "file.zip", onload: () => alert("Done") });
+dl.abort();
+```
+
+### GM_cookie \*
+
+Асинхронно работает с cookie страницы, поддерживая кросс-доменные, HttpOnly и partitioned cookies.
+
+> После v0.17.0-alpha параметры, связанные с `store` и `tabid`, были удалены; ScriptCat теперь решает, брать cookies из окна инкогнито или обычного, исходя из текущего окна.
+
+Нужно объявить оперируемый хост через `@connect`; это объявление разрешает расширению доступ к хосту, поэтому отдельное подтверждение пользователя не запрашивается. Хотя операция `GM_cookie.list` совместима с Tampermonkey, это не рекомендуется ради согласованности.
+
+* `sameSite` не поддерживается.
+
+```typescript
+// name and domain cannot both be empty
+declare function GM_cookie(
+  action: GMTypes.CookieAction,
+  details: GMTypes.CookieDetails,
+  ondone: (cookie: GMTypes.Cookie[], error: unknown | undefined) => void
+): void;
+
+declare namespace GMTypes {
+  type CookieAction = "list" | "delete" | "set";
+  interface CookieDetails {
+    url?: string;
+    name?: string;
+    value?: string;
+    domain?: string;
+    path?: string;
+    secure?: boolean;
+    session?: boolean;
+    httpOnly?: boolean;
+    expirationDate?: number;
+    partitionKey?: CookieDetailsPartitionKeyType;
+  }
+  interface Cookie {
+    domain: string;
+    name: string;
+    value: string;
+    session: boolean;
+    hostOnly: boolean;
+    expirationDate?: number;
+    path: string;
+    httpOnly: boolean;
+    secure: boolean;
+  }
+}
+
+// Callback form
+GM_cookie("list", { url: "https://example.com" }, (cookies) => {
+  console.log(cookies);
+  GM_cookie("set", {
+    name: "foo",
+    value: "bar",
+    domain: "example.com"
+  }, (result) => {
+    console.log(result);
+    GM_cookie("delete", { name: "foo", domain: "example.com" }, (result) => {
+      console.log(result);
+    });
+  });
+});
+
+// Promise form
+const cookies = await GM.cookie.list({ url: "https://example.com" });
+await GM.cookie.set({ name: "foo", value: "bar", domain: "example.com" });
+await GM.cookie.delete("foo", { domain: "example.com" });
+```
+
+**Примечание**: нужно объявить разрешённый домен в метаданных с помощью `@connect example.com`.
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/dev/background.md b/i18n/ru/docusaurus-plugin-content-docs/current/dev/background.md
new file mode 100644
index 00000000..ae37935e
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/dev/background.md
@@ -0,0 +1,343 @@
+---
+title: Фоновый скрипт
+---
+
+Фоновые скрипты подходят для сценариев, которые должны работать постоянно. Это тип скрипта, специфичный для ScriptCat: они выполняются в песочнице и не имеют доступа к DOM. Их можно разрабатывать с теми же GM API, что и в Tampermonkey; замечания по совместимости отмечены в документации.
+
+## Фоновый скрипт (`@background`) {#background-script-background}
+
+Фоновый скрипт объявляется атрибутом `@background`. Он позволяет скрипту продолжать работу в фоне после включения скрипта или запуска браузера.
+
+## Скрипт по расписанию (`@crontab`) {#scheduled-script-crontab}
+
+> Скрипт по расписанию — разновидность фонового скрипта, подходящая для задач, которые нужно **выполнять повторно по временному циклу**.
+
+Скрипт по расписанию объявляется атрибутом `@crontab`. Поддерживается минутное и секундное планирование, а также расширенный синтаксис ScriptCat `once` / `once(...)`, чтобы не запускаться более одного раза в пределах одного временного цикла.
+
+⚠️ Замечания:
+
+* В одном скрипте **действует только первый `@crontab`**
+* Рекомендуется, чтобы **время одного выполнения + время повтора** не превышало интервал cron, иначе запуски могут пересекаться
+
+## Замечания по cron-выражениям
+
+Реализация cron в ScriptCat основана на [**node-cron**](https://github.com/kelektiv/node-cron/) с небольшим расширением стандартного синтаксиса cron.
+
+### Формат выражения
+
+#### Стандартный формат из 5 полей (рекомендуется)
+
+```text
+minute hour day month weekday
+```
+
+#### Расширенный формат из 6 полей (не рекомендуется)
+
+```text
+second minute hour day month weekday
+```
+
+> ⚠️ Формат из 6 полей не рекомендуется
+> В среде браузера нельзя гарантировать секундную точность, и это увеличивает накладные расходы — планирование фоновой страницы может задерживаться.
+
+### Синтаксис, доступный в каждом поле
+
+| Синтаксис | Значение | Пример |
+| ------- | -------------------- | ------------------------ |
+| `*` | Любое значение | `*` (каждую минуту/час) |
+| число | Конкретное значение | `5` (5-я минута) |
+| `a,b,c` | Несколько дискретных значений | `1,15,30` |
+| `a-b` | Непрерывный диапазон | `10-23` |
+| `*/n` | Каждые n единиц | `*/5` |
+| `a-b/n` | Диапазон с шагом | `10-50/10` |
+
+#### Правила для дня недели
+
+* `1–6`: понедельник — суббота
+* `0` или `7`: воскресенье
+
+## Расширенный синтаксис `once`
+
+### Что означает `once`
+
+Использование `once` в cron-выражении означает:
+
+> **В текущем временном цикле допускается только одно успешное выполнение**
+
+Даже если более поздние моменты времени в том же цикле по-прежнему соответствуют правилу cron, скрипт снова не запустится.
+
+### `once` и `once(...)`
+
+| Синтаксис | Базовое значение cron для этого поля | Описание |
+| ------------- | ------------------------------------- | ------------------------------------------------------------------ |
+| `once` | `*` (любое значение) | Запуск при первом совпадении в цикле, без конкретного времени |
+| `once(expr)` | `expr` | Запуск только в моменты, соответствующие `expr` в цикле, и только один раз |
+
+`once(expr)` позволяет точно указать кандидаты по времени, сохраняя правило «не более одного раза за цикл». Внутри скобок поддерживается весь стандартный синтаксис cron (числа, диапазоны, шаги, списки).
+
+Сравнение примеров:
+
+```text
+* once * * *          // any minute of every hour; runs on the first match, no further runs that hour
+* once(9-17) * * *    // between 9:00 and 17:59 every day, runs once per hour
+0,30 once * * *       // whichever of minute 0 or 30 is matched first each hour runs; no further runs that hour
+```
+
+### Позиция `once` = ограничиваемый временной цикл
+
+Где бы ни стояли `once` / `once(...)`, это означает «запускать только один раз в пределах этой временной гранулярности».
+
+| Позиция `once` | Поведение |
+| ---------------- | ------------------------------- |
+| поле минуты | Не более одного раза в минуту |
+| поле часа | Не более одного раза в час |
+| поле дня | Не более одного раза в день |
+| поле месяца | Не более одного раза в месяц |
+| поле дня недели | Не более одного раза в неделю |
+
+Примеры:
+
+```text
+* once * * *       // runs only once per hour
+* * once * *       // runs only once per day
+* 9-18 once * *    // runs only once between 9:00 and 18:59 each day
+```
+
+### `once` в сочетании с диапазонами / списками / шагами
+
+`once` / `once(...)` можно комбинировать с любым синтаксисом cron, но правило одно:
+
+> **В пределах одного цикла после успешного запуска все дальнейшие совпадающие моменты времени игнорируются**
+
+#### Пример 1: диапазон
+
+```text
+* 10 once * *
+```
+
+Смысл:
+
+* Каждый день кандидаты — 10:00–10:59
+* После первого совпадения за день
+* 10:05–10:59 больше не запускаются
+
+#### Пример 2: список
+
+```text
+* 1,3,5 once * *
+```
+
+Смысл:
+
+* Каждый день кандидаты — 1:00, 3:00 и 5:00
+* Если уже был запуск в 1:00
+* 3:00 и 5:00 будут пропущены
+
+#### Пример 3: шаг
+
+```text
+* */4 once * *
+```
+
+Смысл:
+
+* Каждый день кандидаты — 0:00, 4:00, 8:00, 12:00, 16:00 и 20:00
+* После первого запуска за день
+* Дальнейшие моменты времени не выполняются
+
+#### Пример 4: `once(...)` с указанием кандидатов
+
+```text
+* once(9-17) * * *
+```
+
+Смысл:
+
+* Каждый день кандидаты по часам — с 9:00 по 17:00
+* Цикл сбрасывается каждый час; в пределах часа первое совпадение останавливает дальнейшие запуски
+* Итог: один раз в час между 9:00 и 17:00 каждый день, всего 9 раз
+
+```text
+* 9-18 once * *
+```
+
+Смысл:
+
+* Каждый день кандидаты — 9:00–18:59
+* `once` в поле дня фиксирует цикл «раз в день»
+* После первого совпадения за день до 18:59 больше ничего не выполняется
+
+## Примеры `@crontab`
+
+### Обычные
+
+```js
+//@crontab * * * * *        // runs once per minute
+//@crontab * * * * * *      // runs once per second (not recommended)
+//@crontab 0 */6 * * *      // runs on the hour every 6 hours
+//@crontab 15 */6 * * *     // runs at minute 15 every 6 hours
+//@crontab * once * * *     // runs at most once per hour
+//@crontab * * once * *     // runs at most once per day
+//@crontab * 10 once * *    // runs only once within the 10:00 hour each day (e.g. if it ran at 10:04, it won't run again from 10:05-10:59)
+//@crontab * */4 once * *   // checks at most once every 4 hours each day (e.g. if it ran at 4:00, it won't run again at 8, 12, 16, 20, 24, etc.)
+```
+
+### Продвинутые
+
+```js
+//@crontab * 1,3,5 once * *       // runs once at 1:00, 3:00, or 5:00 each day (e.g. if it ran at 1:00, it won't run again at 3:00 or 5:00)
+//@crontab * 10-23 once * *       // runs once between 10:00 and 23:59 each day (e.g. if it ran at 10:04, it won't run again from 10:05-23:59)
+//@crontab * once 13 * *          // runs once per hour on the 13th of every month
+//@crontab * once(9-17) * * *     // runs once per hour between 9:00 and 17:00 each day
+//@crontab 0,30 once * * *        // whichever of minute 0 or 30 is matched first each hour runs; no repeat that hour
+//@crontab * 9-18 once * *        // runs only once between 9:00 and 18:00 each day
+```
+
+## Рекомендации по использованию
+
+### Хорошо подходит для `once`
+
+* Задачи, которые **нужно выполнить только один раз** в день/час
+* Проверки статуса, синхронизация и отчётные скрипты
+* Избежание следующих проблем:
+
+  * Браузер долго не открывали
+  * Задержки планирования фоновой страницы
+  * Повторное выполнение из‑за перезапуска браузера
+
+### Не рекомендуется для `once`
+
+* Задачи, которые должны сработать в точный момент
+* Скрипты, время выполнения которых может заметно превысить интервал cron
+* Задачи со строгими требованиями к числу выполнений
+
+## Проверка cron-выражений
+
+При проверке cron-выражения **временно замените `once` / `once(...)` на их базовое значение**:
+
+* `once` → `*`
+* `once(expr)` → `expr`
+
+Учтите, что тестовые инструменты могут не поддерживать расширенный формат из 6 полей.
+
+Рекомендуемые инструменты:
+
+* [crontab.guru](https://crontab.guru/)
+* [tool.lu cron calculator](https://tool.lu/crontab/)
+
+На странице списка скриптов наведите курсор на **столбец статуса выполнения**, чтобы увидеть **время следующего запланированного запуска**.
+
+## Журналы
+
+На странице списка скриптов при наведении на `столбец статуса выполнения` показывается подсказка со статусом;
+щелчок открывает содержимое журнала, выведенное через `GM_log`.
+
+![](@site/docs/dev/background.assets/image-20210621214143661.png)
+
+![](@site/docs/dev/background.assets/image-20210621214124685.png)
+
+## Отладка скрипта
+
+Фоновые скрипты можно отлаживать прямо со страницы редактора, но с ограничениями:
+
+* `value` синхронизируется некорректно
+* меню `registerMenu` срабатывают некорректно
+
+![](@site/docs/dev/background.assets/image-20210903141601057.png)
+
+Чтобы отладить реальное окружение выполнения, включите **режим разработчика** в настройках расширения, затем откройте страницу расширения `background.html` для отладки.
+
+Ошибки во время выполнения также можно посмотреть в журнале запусков.
+
+![image-20210903144155450](@site/docs/dev/background.assets/image-20210903144155450.png)
+
+## Promise
+
+Настоятельно рекомендуется следующий шаблон — он также позволяет менеджеру скриптов отслеживать выполнение.
+Если скрипт выполняет любую асинхронную операцию, он **должен вернуть `Promise`**.
+
+```ts
+// ==UserScript==
+// @name         Background Script
+// @namespace    wyz
+// @version      1.0.0
+// @author       wyz
+// @background
+// ==/UserScript==
+return new Promise((resolve, reject) => {
+  if (Math.round((Math.random() * 10) % 2)) {
+    resolve("ok"); // succeeded
+  } else {
+    reject("error"); // failed, with the error reason
+  }
+});
+```
+
+```js
+// ==UserScript==
+// @name         Scheduled script that runs once a day
+// @namespace    wyz
+// @version      1.0.0
+// @author       wyz
+// @crontab      * * once * *
+// ==/UserScript==
+return new Promise((resolve, reject) => {
+  if (Math.round((Math.random() * 10) % 2)) {
+    resolve("ok"); // succeeded
+  } else {
+    reject("error"); // failed, with the error reason
+  }
+});
+```
+
+```js
+// ==UserScript==
+// @name         Call an API
+// @namespace    wyz
+// @version      1.0.0
+// @author       wyz
+// @crontab      * * once * *
+// ==/UserScript==
+return new Promise((resolve, reject) => {
+  GM_xmlhttpRequest({
+    url: "https://bbs.tampermonkey.net.cn/",
+    onload() {
+      resolve("ok"); // succeeded
+    },
+    onerror() {
+      reject("error"); // failed, with the error reason
+    },
+  });
+});
+```
+
+Вызывайте `resolve` / `reject` только после того, как логика скрипта действительно завершена.
+После вызова менеджер считает выполнение скрипта завершённым, и последующие операции GM больше не действуют.
+
+## Повтор при ошибке
+
+Фоновые скрипты ScriptCat поддерживают повтор при ошибке.
+При сбое скрипт может вызвать `reject` с `CATRetryError`, чтобы запустить повтор.
+
+* Минимальный интервал повтора: 5 секунд
+* Избегайте конфликта с собственным временем выполнения скрипта, иначе возможно дублирование
+
+```js
+// ==UserScript==
+// @name         Retry example
+// @namespace    https://bbs.tampermonkey.net.cn/
+// @version      0.1.0
+// @description  try to take over the world!
+// @author       You
+// @crontab      * * once * *
+// @grant        GM_notification
+// ==/UserScript==
+
+return new Promise((resolve, reject) => {
+  GM_notification({
+    title: "retry",
+    text: "Retrying in 10 seconds",
+  });
+  reject(new CATRetryError("xxx error", 10));
+});
+```
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/dev/cat-api.md b/i18n/ru/docusaurus-plugin-content-docs/current/dev/cat-api.md
new file mode 100644
index 00000000..d00c87e5
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/dev/cat-api.md
@@ -0,0 +1,135 @@
+---
+title: Документация CatApi
+---
+
+## Обзор
+
+API, специфичные для этого расширения, определяются с префиксом `CAT_`.
+
+Связанные примеры также можно найти в [каталоге example](https://github.com/scriptscat/scriptcat/tree/main/example).
+
+## Определения
+
+### CAT_setProxy
+
+> Устарело начиная со стабильного релиза 0.9.1; в будущем может вернуться в beta-версии.
+
+Задаёт прокси. Учтите, что эта функция будет конфликтовать с расширениями вроде Proxy SwitchyOmega. Несколько скриптов могут использовать прокси без конфликта (например, один скрипт для доступа к Google, другой — к Twitter).
+
+Сначала ознакомьтесь с [PAC](https://developer.mozilla.org/en-US/docs/Web/HTTP/Proxy_servers_and_tunneling/Proxy_Auto-Configuration_PAC_file) и [ограничениями Chromium на полный URL в PAC](https://github.com/FelisCatus/SwitchyOmega/wiki/Chromium-Full-URL-Restriction).
+
+```typescript
+declare function CAT_setProxy(rule: CAT_Types.ProxyRule[] | string): void;
+
+declare namespace CAT_Types {
+  interface ProxyRule {
+    proxyServer: ProxyServer;
+    matchUrl: string[];
+  }
+  type ProxyScheme = "http" | "https" | "quic" | "socks4" | "socks5";
+  interface ProxyServer {
+    scheme?: ProxyScheme;
+    host: string;
+    port?: number;
+  }
+}
+```
+
+### CAT_clearProxy
+
+> Устарело начиная со стабильного релиза 0.9.1; в будущем может вернуться в beta-версии.
+
+Очищает прокси.
+
+```typescript
+declare function CAT_clearProxy(): void;
+```
+
+### CAT_click
+
+> Устарело начиная со стабильного релиза 0.9.1; в будущем может вернуться в beta-версии.
+
+Настоящий клик. API экспериментальное и может измениться или быть удалено.
+
+Реализовано через [Input.dispatchMouseEvent](https://chromedevtools.github.io/devtools-protocol/tot/Input/#method-dispatchMouseEvent). Убедитесь, что элемент находится в видимой области, а координаты отсчитываются относительно окна.
+
+```ts
+declare function CAT_click(x: number, y: number): void;
+```
+
+### CAT_userConfig
+
+Вызов этого API открывает страницу [UserConfig](./config.md) скрипта.
+
+```ts
+declare function CAT_userConfig(): void;
+```
+
+### CAT_fileStorage
+
+Управляет системой хранения, настроенной в менеджере. Для этого API создаётся каталог `app/uuid`; если указан параметр `baseDir`, он используется как базовый каталог.
+
+```ts
+/**
+ * Controls the storage system configured by the manager. An app/uuid directory will be created for this API to use; if the baseDir parameter is specified, it will be used as the base directory instead.
+ * Uploads overwrite files with the same name by default.
+ * @param action Operation type: list lists all files in the given directory, upload uploads a file, download downloads a file, delete deletes a file, config opens the config page. move/mkdir and similar operations are not yet provided.
+ * @param details
+ */
+declare function CAT_fileStorage(
+  action: "list",
+  details: {
+    // File path
+    path?: string;
+    // Base directory; if not set, the script's uuid is used as the directory
+    baseDir?: string;
+    onload?: (files: CATType.FileStorageFileInfo[]) => void;
+    onerror?: (error: CATType.FileStorageError) => void;
+  }
+): void;
+declare function CAT_fileStorage(
+  action: "download",
+  details: {
+    file: CATType.FileStorageFileInfo; // Some platforms require the file's hash, so the file info must be passed in
+    onload: (data: Blob) => void;
+    // onprogress?: (progress: number) => void;
+    onerror?: (error: CATType.FileStorageError) => void;
+    // public?: boolean;
+  }
+): void;
+declare function CAT_fileStorage(
+  action: "delete",
+  details: {
+    path: string;
+    onload?: () => void;
+    onerror?: (error: CATType.FileStorageError) => void;
+    // public?: boolean;
+  }
+): void;
+declare function CAT_fileStorage(
+  action: "upload",
+  details: {
+    path: string;
+    // Base directory; if not set, the script's uuid is used as the directory
+    baseDir?: string;
+    data: Blob;
+    onload?: () => void;
+    // onprogress?: (progress: number) => void;
+    onerror?: (error: CATType.FileStorageError) => void;
+    // public?: boolean;
+  }
+): void;
+declare function CAT_fileStorage(action: "config"): void;
+```
+
+### CAT_scriptLoaded
+
+При использовании `early-start` этой функцией можно определить, полностью ли загрузился скрипт.
+
+```js
+function CAT_ScriptLoaded(): Promise<void>;
+
+CAT_scriptLoaded().then(() => {
+  console.log("Script has fully loaded");
+});
+```
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/dev/cloudcat.md b/i18n/ru/docusaurus-plugin-content-docs/current/dev/cloudcat.md
new file mode 100644
index 00000000..ba1bdefa
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/dev/cloudcat.md
@@ -0,0 +1,91 @@
+---
+title: Облачное выполнение
+---
+
+> Предоставляется несколько способов запуска в облаке; подробности см. в [Средах выполнения](#running-environments). Кроме того, [CloudCat](https://github.com/scriptscat/cloudcat) — сервис для запуска фоновых скриптов в облаке, FAAS-платформа, которая всё ещё в разработке.
+
+⚠ Обратите внимание ⚠: после загрузки в облако смысл `once` в выражении скрипта по расписанию меняется: время до `once` при запуске заменяется на минимальное значение.
+
+Например:
+
+* `* * once * *` => `0 0 * * *`: один раз в день → запуск каждый день в 00:00
+* `* 1-23 once * *` => `0 1 * * *`: один раз между 1:00 и 23:00 каждый день → запуск каждый день в 01:00
+* `* 1,3,5 once * *` => `0 1 * * *`: один раз в 1:00, 3:00 или 5:00 каждый день → запуск каждый день в 01:00
+* `* */4 once * *` => `0 0 * * *`: один раз каждые 4 часа каждый день → запуск каждый день в 00:00
+* `* 1-23/4 once * *` => `0 1 * * *`: один раз каждые 4 часа между 1:00 и 23:00 → запуск каждый день в 01:00
+* `* 10 once * *` => `0 10 * * *`: один раз в 10:00 каждый день → запуск в минуту 00 часа 10 каждый день
+* `* * * once *` => `0 0 1 * *`: один раз в месяц → запуск в 00:00 1-го числа каждого месяца
+
+## Дополнительные описательные значения CloudCat
+
+Скрипт-пример: [Bilibili Auto Check-in](https://scriptcat.org/script-show-page/48)
+
+### cloudCat
+
+Объявление этого атрибута позволяет запускать скрипт через `CloudCat`. Когда у скрипта есть эта опция, в списке скриптов появляется кнопка облачного выполнения; по нажатию можно выбрать способ — см. [Среды выполнения](#running-environments).
+
+![image-20220203225847694](@site/docs/dev/cloudcat.assets/image-20220203225847694.png)
+
+### cloudServer
+
+> Связано с cloudCat, ещё не реализовано
+
+Адрес сервера cloudCat по умолчанию
+
+
+### exportValue
+
+Описывает Values для экспорта в облако; допускается несколько объявлений.
+
+```ts
+// @exportValue key1,key2,key3
+// @exportValue key4,key5,key6
+```
+
+### exportCookie
+
+Описывает cookies для экспорта в облако; допускается несколько объявлений. Параметры описываются через `CookieDetails` из `GM_cookie`, например:
+
+```ts
+// The following exports the cookie named cookie1 from https://docs.scriptcat.org/docs/use/
+// @exportCookie url=https://docs.scriptcat.org/docs/use;name=cookie1
+
+// This exports all cookies for the scriptcat.org domain
+// @exportCookie domain=scriptcat.org
+
+// All available parameters:
+// @exportCookie domain=scriptcat.org;url=https://docs.scriptcat.org/docs/use;name=cookie1;path=/docs/use;secure=true;session=true
+```
+
+## Изменения поддержки API
+> Сейчас поддерживаются только следующие API; если не указано иное, поведение совпадает с исходным API.
+
+### GM_xmlhttpRequest
+
+
+### GM_notification
+
+
+### GM_log
+
+### GM_getValue
+
+Сейчас поддерживается только получение Values, экспортированных через `@exportValue`; set/delete/list и другие методы не поддерживаются.
+
+## Среды выполнения {#running-environments}
+
+### Локально
+
+Экспортируется zip-пакет; после распаковки в папку выполните следующие команды для локального запуска (нужна локальная среда Node.js):
+
+```bash
+npm i
+node index.js
+```
+
+
+### Tencent Cloud
+
+Сначала создайте ключ Tencent Cloud в [**Access Keys**](https://console.cloud.tencent.com/cam/capi) — если используется субаккаунт, выдайте ему права Cloud Function. Затем включите сервис в [**Function Service**](https://console.cloud.tencent.com/scf/list); каждый месяц предоставляется определённый объём бесплатного использования. Регион по умолчанию — Shanghai; при необходимости измените. После нажатия «загрузить» по `@crontab` автоматически создаётся триггер по расписанию для регулярного запуска функции.
+
+![image-20220203224956248](@site/docs/dev/cloudcat.assets/image-20220203224956248.png)
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/dev/config.md b/i18n/ru/docusaurus-plugin-content-docs/current/dev/config.md
new file mode 100644
index 00000000..014ef525
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/dev/config.md
@@ -0,0 +1,69 @@
+---
+title: UserConfig
+---
+
+Содержимое внутри `==UserConfig==` идёт после `==UserScript==` и описывает настраиваемые пользователем параметры скрипта. Конфигурация записывается в формате [YAML](https://yaml.org/):
+
+```js
+/* ==UserConfig==
+group1:
+  configA:                                # key is group.config, e.g. this key is group1.configA
+    title: Config A                       # the config's title
+    description: This is a text-type config # the config's description
+    type: text                            # option type; auto-detected from the data if omitted
+    default: default value                # the config's default value
+    min: 2                                # minimum 2 characters
+    max: 18                               # maximum 18 characters
+    password: true                        # mark as a password field
+  configB:
+    title: Config B
+    description: This is a checkbox config
+    type: checkbox
+    default: true
+  configC:
+    title: Config C
+    description: This is a select-list config
+    type: select
+    default: 1
+    values: [1,2,3,4,5]
+  configD:
+    title: Config D
+    description: This is a dynamic select-list config
+    type: select
+    bind: $cookies                       # dynamically bound values; the key starts with $, and the value must be an array
+  configE:
+    title: Config E
+    description: This is a multi-select-list config
+    type: mult-select
+    default: [1]
+    values: [1,2,3,4,5]
+  configF:
+    title: Config F
+    description: This is a dynamic multi-select-list config
+    type: mult-select
+    bind: $cookies
+  configG:
+    title: Config G
+    description: This is a numeric config
+    type: number
+    default: 1
+    min: 10  # minimum value
+    max: 16  # maximum value
+    unit: min # unit label
+  configH:
+    title: Config H
+    description: This is a long-text config
+    type: textarea
+    default: default value
+---
+group2: # second config group
+  configX:
+    title: Config X
+    description: This is a text-type config
+    default: default value
+ ==/UserConfig== */
+```
+
+После определения здесь в панели управления появляется кнопка конфигурации, с помощью которой пользователь может настроить параметры. Разработчики читают значения через `GM_getValue`, ключ указывается как `group.config`.
+
+![](@site/docs/dev/config.assets/image-20210621213013631.png)
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/dev/index.md b/i18n/ru/docusaurus-plugin-content-docs/current/dev/index.md
new file mode 100644
index 00000000..12a917a1
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/dev/index.md
@@ -0,0 +1,15 @@
+---
+title: Введение
+---
+
+Это расширение поддерживает три типа скриптов:
+
+- Фоновые скрипты страницы (foreground)
+- [Фоновые скрипты](./background.md)
+- [Скрипты по расписанию](./background.md#scheduled-script-crontab)
+
+Фоновые скрипты страницы — то, что обычно имеют в виду под скриптами Tampermonkey. Фоновые скрипты и скрипты по расписанию — типы, специфичные для расширения ScriptCat; подробности смотрите в соответствующей документации.
+
+С помощью этой документации вы можете изучить [API Tampermonkey](./api.md) и [фоновые скрипты ScriptCat](./background.md). Мы также поддерживаем сайт [руководства по разработке скриптов Tampermonkey](https://learn.scriptcat.org/) с большим количеством учебных материалов — добро пожаловать к обсуждению там.
+
+Если вы заметите пробелы в документации, сообщите нам на [GitHub](https://github.com/scriptscat/scriptcat.org) или отправьте PR, чтобы помочь её улучшить.
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/dev/meta.md b/i18n/ru/docusaurus-plugin-content-docs/current/dev/meta.md
new file mode 100644
index 00000000..c3999bf1
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/dev/meta.md
@@ -0,0 +1,212 @@
+---
+title: Блок метаданных
+---
+
+Содержимое внутри `==UserScript==` описывает нужные скрипту разрешения, информацию о скрипте и т.д. Оно располагается в самом начале скрипта.
+
+```js
+// ==UserScript==
+// @name         New Userscript
+// @namespace    https://bbs.tampermonkey.net.cn/
+// @version      0.1.0
+// @description  try to take over the world!
+// @author       You
+// @crontab      * * once * *
+// ==/UserScript==
+```
+
+## Основные значения
+
+### name
+
+Имя скрипта
+
+### namespace
+
+Пространство имён скрипта. `name + namespace` определяет уникальность скрипта.
+
+### version
+
+Версия скрипта. Рекомендуется следовать [семантическому версионированию](https://semver.org/), чтобы при изменении версии пользователю предлагалось обновление и т.д.
+
+### description
+
+Подробное описание скрипта
+
+### author
+
+Автор скрипта
+
+### run-at
+
+Когда запускается скрипт
+
+| Значение | Запуск | Поддерживается с |
+| -------------- | ------------------------------------------------------------------ | ---------------------- |
+| document-start | Внедряет скрипт на страницу, как только URL совпадает на фронтенде | v0.3.0 |
+| document-end | Внедряет скрипт после загрузки DOM; скрипты страницы и изображения ещё могут загружаться | v0.3.0 |
+| document-idle | Внедряет скрипт после полной загрузки всего содержимого | v0.3.0 |
+| document-body | Скрипт внедряется только после появления элемента `body` | v0.6.2 |
+| document-menu | Показывает меню по правому клику; при запуске скрипта в качестве имени меню используется имя скрипта | v0.3.4-v0.9.4 (🔥 удалено) |
+
+Для иконок меню можно обратиться к [Unicode Symbols](https://unicode-table.com/en/) и [emoji](https://www.emojiall.com/en-US/).
+
+### run-in
+
+Указывает окружение внедрения скрипта: `@run-in normal-tabs` для обычных вкладок, `@run-in incognito-tabs` для вкладок инкогнито.
+
+### early-start (v1.1.0+)
+
+Когда `run-at` равен `document-start`, скрипт запускается как можно раньше, но всё равно не гарантирует загрузку быстрее страницы.
+
+После объявления `@run-at document-start` можно добавить `@early-start`, чтобы скрипт загружался быстрее страницы: [пример](https://github.com/scriptscat/scriptcat/blob/main/example/early-start.js)
+
+### inject-into
+
+:::tip
+
+В окружении content-script (`content`) `unsafeWindow` указывает только на собственный `window` окружения и не даёт доступ к `window` страницы.
+
+ScriptCat не поддерживает автоматическую проверку ограничений CSP для выбора внедрения как `content` или `page` (т.е. `@inject-into auto` из Tampermonkey).
+
+:::
+
+Указывает, куда внедряется скрипт: поддерживаются `page` и `content`, по умолчанию `page`.
+
+- `page`: скрипт внедряется в окружение страницы и может через `unsafeWindow` обращаться к `window` и `DOM` страницы
+- `content`: скрипт внедряется в окружение content-script, не может напрямую обращаться к объекту `window` страницы, но может работать с `DOM` страницы и не подчиняется `CSP`
+
+### storageName 🧪
+
+Пространство хранения для `Value`; данные с одним и тем же `storageName` можно совместно использовать и обмениваться ими между скриптами. Специфично для ScriptCat.
+
+### background
+
+Помечает скрипт как фоновый, которому нужно работать в фоновом окружении. Подробности: [Фоновый скрипт](./background.md#background-script-background).
+
+### crontab
+
+Помечает скрипт как скрипт по расписанию; требуется значение cron-выражения. Допускается только одно cron-выражение; выполнение идёт по этому расписанию в фоновом окружении. Подробности: [Скрипт по расписанию](./background.md#scheduled-script-crontab).
+
+### match
+
+Скрипт запускается только для URL, совпадающих с `match`, по правилам [Match patterns](https://developer.chrome.com/docs/extensions/mv3/match_patterns/). В `match` `*` — подстановочный символ, `tld` соответствует домену верхнего уровня, а домен, начинающийся с `*.`, также совпадает с `xxx.com`:
+
+| Значение | Корректные примеры | Некорректные примеры |
+| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| `http://scriptcat.org/doc/match` | `http://scriptcat.org/doc/match` | `http://scriptcat.org/doc/runAt` |
+| `*://*/param?*` | `https://scriptcat.org/param` \| `http://scriptcat.org/param?search=tampermonkey` | `https://scriptcat.org/test/param` |
+| `*://*/prefix*suffix` | `http://scriptcat.org/prefix/suffix` \| `http://scriptcat.org/prefix/mid/suffix` \| `http://scriptcat.org/prefixsuffix` | `http://scriptcat.org/prefix/suffix/end` |
+| `http*://scriptcat.org/*` | `https://scriptcat.org/` \| `https://scriptcat.org/doc` \| `http://scriptcat.org/doc/match` \| `http://scriptcat.org/param?search=tampermonkey` | `https://doc.scriptcat.org/` |
+| `http*://scriptcat.org/doc/*` | `https://scriptcat.org/doc` \| `http://scriptcat.org/doc/match` | `http://scriptcat.org/param?search=tampermonkey` |
+| `http*://scriptcat.tld/doc/*` | `https://scriptcat.cn/doc` \| `http://scriptcat.net.cn/doc/match` | `http://google.com/param?search=tampermonkey` |
+| `http*://*.scriptcat.org/doc/*` | `https://scriptcat.cn/doc` \| `http://www.scriptcat.net.cn/doc/match` | `http://google.com/param?search=tampermonkey` |
+
+### include
+
+Поддерживает `\*` для нечёткого сопоставления, допускает нестандартные URL
+
+### exclude
+
+URL, которые не должны совпадать; синтаксис выражений тот же, что у `include`
+
+### grant
+
+Запрашивает разрешение API — API можно вызывать только после запроса. Список разрешений: [Документация API](./api.md) и [Документация CAT API](./cat-api.md).
+
+Два особых значения:
+
+- **none**: скрипт не выполняется в песочнице, а напрямую в окружении страницы. В этом окружении GM API недоступны, но к объекту `window` страницы можно обращаться напрямую.
+- **unsafeWindow**: в песочнице для доступа к `window` страницы используйте `unsafeWindow`. (Tampermonkey не требует объявлять это — оставлено только для совместимости, что, честно говоря, не очень аккуратно.)
+
+### connect
+
+Запрашивает разрешение доступа к сайту; см. `GM_cookie` и `GM_xmlhttpRequest`. `GM_download` в режиме `native` также учитывает `@connect` (необъявленные хосты вызывают запрос подтверждения, в отличие от Tampermonkey)
+
+### resource
+
+Подключает файл ресурса. После объявления `@resource` информацию можно получить через `GM_getResourceText`/`GM_getResourceURL`.
+
+```js
+// @resource icon https://bbs.tampermonkey.net.cn/favicon.ico
+// @resource html https://bbs.tampermonkey.net.cn/
+// @resource xml https://bbs.tampermonkey.net.cn/sitemap.xml
+// Adding resource integrity verification
+// @resource icon https://bbs.tampermonkey.net.cn/favicon.ico#md5-xxx,sha256-xxx
+```
+
+### require
+
+Подключает внешний JS-файл; поддерживает [проверку целостности ресурса](#resource-integrity-verification)
+
+### require-css
+
+Подключает внешний CSS-файл; поддерживает [проверку целостности ресурса](#resource-integrity-verification)
+
+### noframes
+
+Помечает, что скрипт не должен выполняться внутри `<frame>`
+
+### definition
+
+Адрес ссылки на файл `.d.ts`, включающий подсказки автодополнения в редакторе
+
+### antifeature
+
+Связано с маркетплейсом скриптов; нежелательные возможности нужно помечать этим описательным значением, например:
+
+```js
+// @antifeature ads This script has ads
+// @antifeature referral-link This script modifies or redirects to the author's referral link
+```
+
+## Дополнительные описательные значения
+
+### license
+
+Лицензия с открытым исходным кодом текущего скрипта
+
+### updateURL
+
+Для проверки обновлений у удалённого скрипта должен быть тег `@version`.
+
+Ссылка, по которой скрипт проверяет обновления; если не задана, по умолчанию используется `user.js => meta.js` ссылки либо текущая ссылка, если `user.js` нет.
+
+Если настроен `@updateURL`, для его действия также нужно настроить `@downloadURL`.
+
+### downloadURL
+
+Адрес загрузки обновления скрипта
+
+### supportURL
+
+Сайт поддержки, страница сообщений об ошибках
+
+### homepage, homepageURL, website
+
+Домашняя страница скрипта
+
+### source
+
+Страница исходного кода скрипта
+
+### icon, iconURL, defaulticon
+
+Иконка скрипта
+
+### icon64, icon64URL
+
+Иконка скрипта размером 64x64
+
+### Примечания
+
+### Проверка целостности ресурса {#resource-integrity-verification}
+
+- Используйте md5, sha1, sha256, sha384 или sha512 для проверки ресурсов на подмену. Несколько методов проверки можно разделить `;` или `,`.
+- Согласно [рекомендациям W3C](https://w3c.github.io/webappsec-subresource-integrity/#hash-collision-attacks), md5 и sha1 не рекомендуются; используйте sha384 или более сильный алгоритм хеширования.
+
+Например:
+
+```js
+// @require https://cdn.jsdelivr.net/npm/darkmode-js@1.5.7/lib/darkmode-js.min.js#md5-d55836f30c097da753179f82fa6f108f,sha256-a476ab8560837a51938aa6e1720c8be87c2862b6221690e9de7ffac113811a90
+```
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/dev/subscribe.md b/i18n/ru/docusaurus-plugin-content-docs/current/dev/subscribe.md
new file mode 100644
index 00000000..5462b5a9
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/dev/subscribe.md
@@ -0,0 +1,56 @@
+---
+title: Режим подписки
+---
+
+Файл должен начинаться с `UserSubscribe` вместо `UserScript`. Ссылка для установки должна использовать расширение `user.sub.js` и быть ссылкой `https`.
+
+Скрипт подписки показывает диалог установки только для подтверждения подписки пользователем; последующие обновления выполняются тихо, и диалог обновления снова показывается только при изменении разрешения `connect`.
+
+Один скрипт подписки может описывать ссылки установки для нескольких скриптов. Скрипты, установленные через режим подписки, устанавливаются тихо, без диалога подтверждения, и по-прежнему отображаются в списке скриптов — но их разрешение `connect` берётся из `connect`, объявленного в подписке, а не из собственного `connect` скрипта.
+
+```js
+// ==UserSubscribe==
+// @name         xxx
+// @description  Subscribe to the xxx script series
+// @version      0.1.0
+// @author       You
+// @connect      www.baidu.com
+// @scriptUrl    https://script.tampermonkey.net.cn/48.user.js
+// @scriptUrl    https://script.tampermonkey.net.cn/49.user.js
+// ==/UserSubscribe==
+```
+
+## Обновления подписки и обновления скриптов
+
+Согласно настроенному пользователем `интервалу обновления`, ScriptCat периодически проверяет ссылку подписки; для этого должен быть задан `version`.
+
+При каждом обновлении или изменении подписки ссылки скриптов сравниваются с уже установленными: скрипты, отсутствующие в новой подписке, удаляются, а новые устанавливаются тихо. Обновления скриптов следуют собственному `version` скрипта с той же логикой, что и при обычной установке.
+
+## Тихая установка и обновление
+
+Подписанные скрипты устанавливаются и обновляются тихо — добавление, удаление или обновление скрипта из подписки показывает только уведомление, без повторного подтверждения пользователем. Из‑за этого механизма тихих обновлений подписывайтесь только на доверенные источники.
+
+
+## metadata
+
+В скрипте подписки смысл некоторых полей метаданных меняется.
+
+### name
+
+Имя подписки (также можно редактировать прямо в списке подписок)
+
+### description
+
+Описание подписки — для чего она предназначена
+
+### version
+
+Версия подписки. Если опущена, обновления вместо этого запускаются при изменении содержимого скрипта подписки.
+
+### connect
+
+Запрашивает разрешение доступа к сайту; см. `GM_cookie` и `GM_xmlhttpRequest`. Для скриптов, установленных через режим подписки, `connect` переопределяется `connect` подписки.
+
+### scriptUrl
+
+Ссылки установки скриптов, необходимые подписке
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/script_installation.md b/i18n/ru/docusaurus-plugin-content-docs/current/script_installation.md
new file mode 100644
index 00000000..ab42d126
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/script_installation.md
@@ -0,0 +1,9 @@
+---
+title: Установка скрипта
+---
+
+Эта страница используется как промежуточный шаг при установке нового пользовательского скрипта в `ScriptCat`.
+
+После завершения установки страница должна автоматически закрыться или выполнить перенаправление.
+
+Страница не предназначена для прямого просмотра. При необходимости откройте [Установка скриптов](/docs/use/script_installation/).
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/sponsor/index.md b/i18n/ru/docusaurus-plugin-content-docs/current/sponsor/index.md
new file mode 100644
index 00000000..a8b6a6f3
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/sponsor/index.md
@@ -0,0 +1,43 @@
+---
+sidebar: false
+title: Спонсорство ScriptCat
+description: Поддержите ScriptCat — открытый менеджер пользовательских скриптов, который ведут волонтёры. Как стать спонсором и где отображаются спонсоры.
+icon: heart
+---
+
+import SponsorBlock from '@site/src/components/SponsorBlock/en.mdx';
+
+ScriptCat — открытый проект, поддерживаемый волонтёрами, без корпоративной поддержки. Серверы, домены и прочая инфраструктура, а также большое количество времени на разработку и сопровождение обеспечиваются поддержкой сообщества. Каждый вклад помогает ScriptCat развиваться дальше.
+
+## Куда идут средства спонсорства
+
+Доходы от спонсорства в основном идут на:
+
+- **покрытие операционных расходов** — серверы, домены и повседневная инфраструктура;
+- **вознаграждение мейнтейнеров и участников** — чтобы долгосрочные мейнтейнеры и все, кто вносит код, переводы и документацию, получали заслуженную поддержку;
+- **разработку новых возможностей** — больше времени на полировку пользовательского опыта и создание новых функций.
+
+## Как стать спонсором
+
+Неважно, частное вы лицо или компания, и каков размер поддержки — каждый вклад имеет значение.
+
+Мы принимаем спонсорские взносы через [OpenCollective](https://opencollective.com/scriptcat): разовые или ежемесячные; после пожертвования ваше имя появится в списке спонсоров (backers).
+
+Если вам нужен **спонсорский плейсмент** — логотип и описание в README, на сайте или в документации — напишите нам на [codfrm@gmail.com](mailto:codfrm@gmail.com).
+
+## Спонсорские плейсменты
+
+Логотип и описание спонсора могут отображаться в следующих местах (по договорённости по электронной почте):
+
+| Место | Формат |
+| --- | --- |
+| Верх GitHub README | Большой баннер |
+| Блок спонсоров в GitHub README | Логотип + однострочное описание |
+| Страница спонсоров на сайте (эта страница) | Логотип + описание |
+| Страницы документации на сайте (например, changelog) | Отображение логотипа |
+
+## Наши спонсоры
+
+Спасибо следующим спонсорам за поддержку ScriptCat ❤️
+
+<SponsorBlock />
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/use/QA.md b/i18n/ru/docusaurus-plugin-content-docs/current/use/QA.md
new file mode 100644
index 00000000..827e195f
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/use/QA.md
@@ -0,0 +1,49 @@
+---
+title: Часто задаваемые вопросы
+---
+
+## Режим разработчика / разрешения для пользовательских скриптов
+
+#### В: ScriptCat показывает «Режим разработчика не включён», скрипты не работают?
+
+Начиная с Chrome 120+ и новых версий Edge браузеры требуют вручную включить разрешения для запуска скриптов. См. [Включение поддержки пользовательских скриптов](/docs/use/open-dev/).
+
+Если разрешение уже включено, а предупреждение остаётся — перезапустите браузер или перезагрузите расширение.
+
+## Скрипты не работают
+
+#### В: Установил(а) скрипт, но эффекта нет?
+
+1. **Не включено «Allow User Scripts»** — см. [Включение поддержки пользовательских скриптов](/docs/use/open-dev/)
+2. **Холодный старт** — сразу после открытия браузера скрипты могут ещё не загрузиться. Обновите страницу
+3. **Конфликт расширений** — блокировщики рекламы (например, uBlock Origin) могут вызывать ошибки скриптов
+
+#### В: Скрипт работает в Tampermonkey, но не в ScriptCat?
+
+Реализации API ScriptCat и Tampermonkey немного отличаются. Обновитесь до последней версии. Если проблема остаётся — создайте Issue на [GitHub](https://github.com/scriptscat/scriptcat/issues).
+
+## Проблемы облачной синхронизации
+
+> Базовое использование синхронизации: [Синхронизация и резервное копирование](/docs/use/sync/).
+
+#### В: Проблемы с синхронизацией OneDrive / Google Drive / WebDAV?
+
+1. **Удалённые скрипты появляются снова** — включите «синхронизацию удаления» на всех устройствах
+
+## Проблемы установки скриптов
+
+> Как устанавливать скрипты: [Установка скриптов](/docs/use/script_installation/).
+
+## Проблемы с авторизацией Cookie
+
+#### В: GM_cookie не получает cookies?
+
+1. **Не появляется окно авторизации** — убедитесь, что `GM_cookie` объявлен в `@grant` скрипта, и через `@connect` указаны нужные домены
+
+## Потеря данных скриптов
+
+#### В: После открытия браузера все скрипты пропали?
+
+1. **Задержка инициализации** — при старте браузера ScriptCat ещё может загружать данные. Подождите несколько секунд или перезапустите браузер
+2. **«Чистильщики»** — 360 Security Guard, CCleaner и подобные могут удалять данные расширений. Исключите данные расширений браузера в настройках очистки
+3. **Регулярные бэкапы** — используйте экспорт или [облачную синхронизацию](/docs/use/sync/) для резервного копирования скриптов и настроек
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/use/from-other/migrate-from-tampermonkey.md b/i18n/ru/docusaurus-plugin-content-docs/current/use/from-other/migrate-from-tampermonkey.md
new file mode 100644
index 00000000..39c87644
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/use/from-other/migrate-from-tampermonkey.md
@@ -0,0 +1,27 @@
+---
+title: Миграция из Tampermonkey в ScriptCat
+---
+
+Если вы сейчас используете Tampermonkey и хотите перейти на ScriptCat, ниже приведены шаги и советы, которые помогут выполнить миграцию без проблем.
+
+## Экспорт резервной копии из Tampermonkey
+
+Сначала нажмите значок Tampermonkey, чтобы открыть панель управления.
+
+![image-20250716225507707](@site/i18n/en/docusaurus-plugin-content-docs/current/use/from-other/migrate-from-tampermonkey.assets/image-20250716225507707.webp)
+
+Нажмите `Utilities`, затем в разделе zip-файла нажмите `Export`, чтобы экспортировать zip-файл.
+
+![image-20250716225611932](@site/i18n/en/docusaurus-plugin-content-docs/current/use/from-other/migrate-from-tampermonkey.assets/image-20250716225611932.webp)
+
+## Импорт в ScriptCat
+
+В расширении ScriptCat нажмите значок панели управления, чтобы открыть интерфейс управления.
+
+![image-20250716225719787](@site/i18n/en/docusaurus-plugin-content-docs/current/use/from-other/migrate-from-tampermonkey.assets/image-20250716225719787.webp)
+
+Выберите `Tools`, затем нажмите `Import File`, укажите ранее экспортированный zip-файл Tampermonkey и нажмите `Open` для импорта.
+
+![image-20250716225741428](@site/i18n/en/docusaurus-plugin-content-docs/current/use/from-other/migrate-from-tampermonkey.assets/image-20250716225741428.webp)
+
+На открывшейся странице выберите нужные скрипты (или выберите все) и нажмите кнопку `Import`.
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/use/from-other/migrate-from-violentmonkey.md b/i18n/ru/docusaurus-plugin-content-docs/current/use/from-other/migrate-from-violentmonkey.md
new file mode 100644
index 00000000..2ea16e14
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/use/from-other/migrate-from-violentmonkey.md
@@ -0,0 +1,27 @@
+---
+title: Миграция из Violentmonkey в ScriptCat
+---
+
+Если вы сейчас используете Violentmonkey и хотите перейти на ScriptCat, ниже приведены шаги и советы, которые помогут выполнить миграцию без проблем.
+
+## Экспорт резервной копии из Violentmonkey
+
+Сначала нажмите значок Violentmonkey, чтобы открыть панель управления.
+
+![image-20250716225900597](@site/i18n/en/docusaurus-plugin-content-docs/current/use/from-other/migrate-from-violentmonkey.assets/image-20250716225900597.webp)
+
+Нажмите `Settings`, затем нажмите `Export as zip file`, чтобы экспортировать файл резервной копии.
+
+![image-20250716225935258](@site/i18n/en/docusaurus-plugin-content-docs/current/use/from-other/migrate-from-violentmonkey.assets/image-20250716225935258.webp)
+
+## Импорт в ScriptCat
+
+В расширении ScriptCat нажмите значок панели управления, чтобы открыть интерфейс управления.
+
+![image-20250716225719787](@site/i18n/en/docusaurus-plugin-content-docs/current/use/from-other/migrate-from-tampermonkey.assets/image-20250716225719787.webp)
+
+Выберите `Tools`, затем нажмите `Import File`, укажите ранее экспортированный zip-файл Violentmonkey и нажмите `Open` для импорта.
+
+![image-20250716225741428](@site/i18n/en/docusaurus-plugin-content-docs/current/use/from-other/migrate-from-tampermonkey.assets/image-20250716225741428.webp)
+
+На открывшейся странице выберите нужные скрипты (или выберите все) и нажмите кнопку `Import`.
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/use/install_comple.md b/i18n/ru/docusaurus-plugin-content-docs/current/use/install_comple.md
new file mode 100644
index 00000000..b5f0fed7
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/use/install_comple.md
@@ -0,0 +1,80 @@
+---
+title: Установка завершена
+hide_title: true
+sidebar_class_name: hidden
+---
+
+import GithubStar from '@site/src/components/GithubStar';
+import SponsorBlock from '@site/src/components/SponsorBlock/en.mdx';
+
+# 🎉 Добро пожаловать в ScriptCat
+
+Поздравляем: расширение ScriptCat успешно установлено! ScriptCat — мощный менеджер пользовательских скриптов, совместимый со скриптами Tampermonkey и с множеством дополнительных возможностей.
+
+<GithubStar variant="bar" scene="install" />
+
+<SponsorBlock />
+
+## Важное о безопасности
+
+⚠️ **Пользовательские скрипты очень мощные — безопасность критична!**
+
+Скрипты могут читать и изменять содержимое страниц, поэтому **безопасность крайне важна**. Чтобы защитить личные данные и устройство:
+
+- ✅ **Устанавливайте скрипты только с доверенных сайтов**
+- ✅ **Внимательно смотрите рейтинги и отзывы**
+- ✅ **Понимайте, что делает скрипт и какие разрешения запрашивает**
+- ❌ **Не скачивайте скрипты с неизвестных или подозрительных источников**
+- ❌ **Не устанавливайте файлы скриптов неизвестного происхождения**
+
+### Рекомендуемые доверенные источники
+
+Рекомендуем брать скрипты здесь:
+
+- **[Сайт скриптов ScriptCat](https://scriptcat.org/)** — официальный сайт, поддерживаемый ScriptCat
+- **[GreasyFork](https://greasyfork.org/)** — крупнейший в мире сайт userscripts
+- **[Userscript.Zone](https://www.userscript.zone/)** — подборка качественных скриптов
+
+## Что дальше
+
+### Откройте интерфейс управления
+
+Нажмите значок ScriptCat на панели инструментов браузера, затем кнопку «⚙️» в правом верхнем углу, чтобы открыть интерфейс управления.
+
+### Установите первый скрипт
+
+В всплывающем окне нажмите меню «⋮» в правом верхнем углу и выберите «Получить скрипты» — откроется официальный сайт скриптов.
+
+### Изучите возможности
+
+- 📊 **Управление скриптами**: включение/выключение, статус работы
+- 🔧 **Настройки**: параметры скриптов и правила запуска
+- 📝 **Редактор**: создание и правка своих скриптов
+- 🔄 **Синхронизация**: настройки и скрипты на нескольких устройствах
+
+## Рекомендации
+
+1. **Начните с простого**: новым пользователям лучше ставить простые скрипты с высоким рейтингом
+2. **Проверяйте обновления**: регулярно обновляйте установленные скрипты
+3. **Делайте резервные копии**: важные конфигурации стоит бэкапить
+4. **Сообщайте о проблемах**: через [GitHub](https://github.com/scriptscat/scriptcat) или официальное сообщество
+
+## Отказ от ответственности
+
+При использовании ScriptCat важно понимать:
+
+- ScriptCat предоставляет среду выполнения, но не отвечает за безопасность, работу или содержимое сторонних скриптов
+- Риски использования сторонних скриптов несёте вы
+- Рекомендуется внимательно читать исходный код и документацию скрипта
+
+Подробности: [Полный отказ от ответственности](/docs/use/policy/disclaimer/)
+
+---
+
+**Готовы начать путь с ScriptCat? Нажмите значок расширения и откройте безграничные возможности!**
+
+Если нужна помощь:
+
+- 📖 [Документация](/docs/use/use/)
+- 🎓 [Гайд по разработке скриптов](https://learn.scriptcat.org/)
+- 💬 [Сообщество пользователей](https://discord.gg/JF76nHCCM7)
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/use/open-dev.md b/i18n/ru/docusaurus-plugin-content-docs/current/use/open-dev.md
new file mode 100644
index 00000000..3d3cbc39
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/use/open-dev.md
@@ -0,0 +1,147 @@
+---
+title: Включение поддержки пользовательских скриптов в браузере
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import { Icon } from "@iconify/react";
+import BrowserGuide from '@site/src/components/BrowserGuide';
+import GithubStar from '@site/src/components/GithubStar';
+import SponsorBlock from '@site/src/components/SponsorBlock/en.mdx';
+
+
+<GithubStar variant="bar" scene="install" />
+
+<BrowserGuide texts={{
+  allowUserScripts: {
+    title: "Ваш браузер поддерживает «Разрешить пользовательские скрипты»",
+    description: "Следуйте шагам ниже, чтобы включить параметр «Разрешить пользовательские скрипты» и нормально пользоваться ScriptCat.",
+    button: "Смотреть шаги",
+    anchor: "#allow-user-scripts",
+  },
+  devMode: {
+    title: "В вашем браузере нужно включить «Режим разработчика»",
+    description: "Следуйте шагам ниже, чтобы включить «Режим разработчика» и нормально пользоваться ScriptCat.",
+    button: "Смотреть шаги",
+    anchor: "#enable-developer-mode",
+  },
+  legacy: {
+    title: "Версия браузера слишком старая",
+    description: "Ваш браузер не поддерживает Manifest V3. Нужно вручную установить устаревший ScriptCat (v0.16.x). См. инструкции ниже.",
+  },
+  nonChromium: {
+    title: "Chromium-браузер не обнаружен",
+    description: "ScriptCat сейчас поддерживает только браузеры на базе Chromium (Chrome, Edge и т.д.). Если вы используете такой браузер, проигнорируйте это сообщение и следуйте шагам ниже.",
+  },
+}} />
+
+<SponsorBlock />
+
+## Разрешить пользовательские скрипты {#allow-user-scripts}
+
+[Allow User Scripts](https://developer.chrome.com/docs/extensions/reference/api/userScripts?hl=en#chrome_versions_138_and_newer_allow_user_scripts_toggle) — новая возможность Manifest V3, позволяющая запускать пользовательские скрипты в браузере.
+
+<Tabs groupId="browser" queryString>
+  <TabItem value="edge" label={<div className="flex items-center gap-1"><Icon height={16} width={16} icon="logos:microsoft-edge" />Edge</div>} default>
+
+① Откройте управление расширениями браузера или перейдите на [edge://extensions/](edge://extensions/)
+
+![edge-open-settings](@site/i18n/en/docusaurus-plugin-content-docs/current/use/open-dev.assets/edge-extensions-page.webp)
+
+② Найдите расширение ScriptCat и нажмите `Details` / «Сведения»
+
+![edge-extensions-details](@site/i18n/en/docusaurus-plugin-content-docs/current/use/open-dev.assets/edge-extensions-details.png)
+
+③ На странице сведений ScriptCat найдите параметр `Allow user scripts` / «Разрешить пользовательские скрипты» и включите его. Затем отключите и снова включите расширение или перезапустите браузер.
+
+> ⚠️⚠️⚠️ Для более старых Edge (≤143) или если этого параметра нет, см. [Включение режима разработчика](#enable-developer-mode)
+
+![edge-allow-user-scripts](@site/i18n/en/docusaurus-plugin-content-docs/current/use/open-dev.assets/edge-allow-user-scripts.png)
+
+  </TabItem>
+  <TabItem value="chrome" label={<div className="flex items-center gap-1"><Icon height={16} width={16} icon="logos:chrome" />Chrome</div>}>
+
+① Откройте управление расширениями или перейдите на [chrome://extensions/](chrome://extensions/)
+
+![chrome-open-settings](@site/i18n/en/docusaurus-plugin-content-docs/current/use/open-dev.assets/chrome-extensions-page.webp)
+
+② Найдите расширение ScriptCat и нажмите `Details` / «Сведения»
+
+![scriptcat-extension-details](@site/i18n/en/docusaurus-plugin-content-docs/current/use/open-dev.assets/scriptcat-extension-details.webp)
+
+③ На странице сведений ScriptCat найдите `Allow user scripts` / «Разрешить пользовательские скрипты» и включите. Затем отключите и снова включите расширение или перезапустите браузер.
+
+![allow-user-scripts-toggle](@site/i18n/en/docusaurus-plugin-content-docs/current/use/open-dev.assets/allow-user-scripts-toggle.webp)
+</TabItem>
+  <TabItem value="edge-mobile" label={<div className="flex items-center gap-1"><Icon height={16} width={16} icon="logos:microsoft-edge" />Edge Mobile</div>}>
+
+Для Edge Mobile с версией движка ≥ 138 режим разработчика не обязателен. Включите `Allow user scripts` в настройках расширения.
+
+① Откройте список расширений Edge Mobile, найдите ScriptCat и нажмите `⋮` справа
+
+② Во всплывающих настройках расширения включите `Allow user scripts`
+
+③ Отключите и снова включите расширение или перезапустите браузер.
+
+> ⚠️⚠️⚠️ Для движка ниже 138 или если параметра нет, см. [Включение режима разработчика](#enable-developer-mode)
+
+![edge-mobile-allow-user-scripts](@site/i18n/en/docusaurus-plugin-content-docs/current/use/open-dev.assets/edge%20mobile%20138.png)
+
+  </TabItem>
+</Tabs>
+
+## Включение режима разработчика {#enable-developer-mode}
+
+<Tabs groupId="browser" queryString>
+  <TabItem value="edge" label={<div className="flex items-center gap-1"><Icon height={16} width={16} icon="logos:microsoft-edge" /><span>Edge</span></div>} default>
+
+① Откройте управление расширениями или [edge://extensions/](edge://extensions/)
+
+![edge-open-settings](@site/i18n/en/docusaurus-plugin-content-docs/current/use/open-dev.assets/edge-extensions-page.webp)
+
+② Включите `Developer mode` / «Режим разработчика» (в некоторых браузерах он может быть в другом месте, например 360: Дополнительное управление > Режим разработчика)
+
+![edge-open-dev](@site/i18n/en/docusaurus-plugin-content-docs/current/use/open-dev.assets/edge-developer-mode-toggle.webp)
+
+③ После включения отключите и снова включите расширение или перезапустите браузер.
+
+  </TabItem>
+  <TabItem value="chrome" label={<div className="flex items-center gap-1"><Icon height={16} width={16} icon="logos:chrome" /><span>Chrome</span></div>}>
+
+① Откройте управление расширениями или [chrome://extensions/](chrome://extensions/)
+
+![chrome-open-settings](@site/i18n/en/docusaurus-plugin-content-docs/current/use/open-dev.assets/chrome-extensions-page.webp)
+
+② Включите `Developer mode` / «Режим разработчика» (в некоторых браузерах он может быть в другом месте)
+
+![chrome-open-dev](@site/i18n/en/docusaurus-plugin-content-docs/current/use/open-dev.assets/chrome-developer-mode-toggle.webp)
+
+③ После включения отключите и снова включите расширение или перезапустите браузер.
+
+  </TabItem>
+
+<TabItem value="edge-mobile" label={<div className="flex items-center gap-1"><Icon height={16} width={16} icon="logos:microsoft-edge" /><span>Edge Mobile</span></div>}>
+
+Для Edge Mobile с движком ниже 138 или без параметра `Allow user scripts` нажмите кнопку настроек вверху страницы расширений и включите режим разработчика.
+
+![edge-mobile-open-dev](@site/i18n/en/docusaurus-plugin-content-docs/current/use/open-dev.assets/edge%20mobile.png)
+</TabItem>
+
+</Tabs>
+
+:::warning Устаревшие версии
+
+Если вы используете Windows 8/7/XP или версия движка браузера ниже 120, нужно вручную установить [устаревший ScriptCat](https://bbs.tampermonkey.net.cn/thread-3068-1-1.html). v0.16.x — последняя версия с поддержкой Manifest V2. Шаги установки: [Загрузка распакованного расширения](./use.md#load-unpacked-extension-installation).
+
+:::
+
+<details>
+<summary>Технический фон: Manifest V3</summary>
+
+Из‑за ограничений браузеров расширения переводят на Manifest V3, а расширения Manifest V2 полностью отключают после июня 2025. В рамках Manifest V3 для нормальной работы ScriptCat нужно включить режим разработчика или поддержку пользовательских скриптов.
+
+Справка: [Developer mode for extension users](https://developer.chrome.com/docs/extensions/reference/api/userScripts?hl=en#developer_mode_for_extension_users), [Manifest V3](https://developer.chrome.com/docs/extensions/develop/migrate/what-is-mv3?hl=en)
+
+Для движка ≥ 138 включайте «Allow User Scripts». Для более старых версий — «Режим разработчика».
+
+</details>
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/use/policy/disclaimer.md b/i18n/ru/docusaurus-plugin-content-docs/current/use/policy/disclaimer.md
new file mode 100644
index 00000000..a97b7814
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/use/policy/disclaimer.md
@@ -0,0 +1,20 @@
+---
+title: Отказ от ответственности ScriptCat
+sidebar_label: Отказ от ответственности
+---
+
+Продукты и сервисы, связанные со ScriptCat (включая, но не ограничиваясь, браузерные расширения, сайты скриптов, API-сервисы и т.д., совместно именуемые «Сервисы»), разрабатываются и предоставляются командой ScriptCat (далее — «мы» или «разработчики»). Перед началом использования наших сервисов внимательно прочитайте следующий отказ от ответственности. Доступ, скачивание, установка и использование любых наших продуктов или сервисов считаются безоговорочным принятием всего содержания настоящего заявления.
+
+1. Наши сервисы, а также всё их содержимое и функциональность предоставляются по принципу «как есть» и «по мере доступности», без каких-либо явных или подразумеваемых гарантий. Мы не гарантируем производительность, функциональность или доступность сервисов, а также не гарантируем, что сервисы будут работать без ошибок или что любые ошибки будут исправлены.
+
+2. Ни при каких обстоятельствах команда ScriptCat, участники проекта или любые связанные лица не несут ответственности за любые прямые, косвенные, случайные, особые, штрафные или последующие убытки, включая, но не ограничиваясь, потерей данных, упущенной выгодой, повреждением оборудования или перерывом в деятельности, независимо от того, возникли ли такие убытки вследствие использования или невозможности использования наших сервисов, даже если о возможности таких убытков было известно заранее.
+
+3. Вы соглашаетесь принять на себя все риски, связанные с использованием наших сервисов. Вы должны понимать риски безопасности, которые могут возникнуть при скачивании и использовании сторонних скриптов, включая, но не ограничиваясь, вредоносным ПО или утечками данных. Мы не отвечаем за безопасность, функциональность или содержимое любых сторонних скриптов и не берём на себя обязанность проверять содержимое скриптов, загружаемых или распространяемых пользователями.
+
+4. Все права интеллектуальной собственности на наши сервисы, включая авторские права, товарные знаки, знаки обслуживания и патентные права, принадлежат их разработчикам или лицензиарам. Без явного письменного согласия разработчиков или их лицензиаров вы не вправе копировать, изменять, повторно публиковать или иным образом использовать эти материалы.
+
+5. Мы оставляем за собой право изменять, приостанавливать или прекращать предоставление сервисов в любое время без предварительного уведомления пользователей. Мы не несём ответственности перед пользователями или третьими лицами за любые изменения, изменение цен, приостановку или прекращение сервисов.
+
+6. Право окончательного толкования содержания настоящего заявления принадлежит команде ScriptCat.
+
+Используя любые сервисы ScriptCat, вы подтверждаете, что прочитали и поняли этот отказ от ответственности и согласны с его условиями. Если у вас есть вопросы по этому отказу от ответственности, вы можете связаться с нами по электронной почте: \<yz@ggnb.top> или через способы обратной связи в продукте.
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/use/policy/privacy.md b/i18n/ru/docusaurus-plugin-content-docs/current/use/policy/privacy.md
new file mode 100644
index 00000000..18fa02be
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/use/policy/privacy.md
@@ -0,0 +1,71 @@
+---
+title: Политика конфиденциальности
+---
+
+Добро пожаловать в браузерное расширение ScriptCat! ScriptCat (далее — «наш продукт») — браузерное расширение, разработанное и управляемое scriptcat.org (далее — «мы»).
+
+**Мы глубоко понимаем важность защиты конфиденциальности и с самого начала проектирования придерживаемся принципа приоритета конфиденциальности.**
+
+Если при чтении этой политики у вас возникнут вопросы, свяжитесь с нами по адресу [yz@ggnb.top](mailto:yz@ggnb.top) или через функцию обратной связи в продукте.
+
+## Основное обязательство
+
+**Мы торжественно обещаем: ScriptCat не собирает ваши персональные данные и не получает доступ к содержимому ваших скриптов или к данным о просмотре.**
+
+## Подробное описание
+
+### 1. Мы не собираем персональные данные
+
+Философия проектирования ScriptCat — защита конфиденциальности пользователя. Наш продукт:
+
+- **не собирает** персональные идентификационные данные (например, имя, адрес электронной почты, номер телефона и т.п.);
+- **не собирает** историю просмотра, историю поиска или другие данные об онлайн-активности;
+- **не собирает** сведения об устройстве, данные о местоположении или иные технические идентификаторы;
+- **не собирает** содержимое установленных скриптов или предпочтения использования.
+
+### 2. Локальная обработка данных
+
+Основные функции ScriptCat выполняются полностью на вашем локальном устройстве:
+
+- пользовательские скрипты и их настройки в основном хранятся в локальном браузере;
+- выполнение скриптов и обработка данных выполняются локально;
+- мы не можем получить доступ к содержимому ваших скриптов, данным о просмотре или иной личной информации.
+
+**Об облачной синхронизации:**
+
+- облачная синхронизация — необязательная функция, которую нужно включить самостоятельно;
+- данные синхронизации передаются напрямую между вашим устройством и выбранным вами облачным сервисом;
+- для стабильности работы синхронизации мы временно храним необходимые технические учётные данные, но не получаем доступ к содержимому синхронизации.
+
+### 3. Обеспечение безопасности данных
+
+Поскольку мы не собираем персональные данные, вопроса хранения персональных данных не возникает. Мы обещаем:
+
+- все ваши данные сохраняются на вашем устройстве;
+- мы не можем получить доступ к вашим локальным данным;
+- даже при желании мы не смогли бы получить ваши персональные данные.
+
+### 4. О сторонних сервисах
+
+Хотя сам ScriptCat данные не собирает, обратите внимание:
+
+- установленные вами пользовательские скрипты могут взаимодействовать со сторонними сайтами или сервисами;
+- такое взаимодействие регулируется политиками конфиденциальности соответствующих третьих сторон и не входит в сферу действия настоящей политики;
+- рекомендуем перед установкой скриптов ознакомиться с их функциями и запрашиваемыми разрешениями.
+
+### 5. Обновления политики
+
+Мы можем обновлять настоящую политику конфиденциальности в связи с требованиями законодательства или изменениями функций продукта. Обновлённая политика публикуется на официальном сайте; рекомендуем периодически проверять актуальную версию. Продолжение использования нашего продукта означает принятие обновлённой политики.
+
+### 6. Связь с нами
+
+Если у вас есть вопросы или предложения по настоящей политике конфиденциальности, свяжитесь с нами:
+
+- электронная почта: [yz@ggnb.top](mailto:yz@ggnb.top);
+- через функцию обратной связи в продукте.
+
+---
+
+Последнее обновление: июль 2025
+
+Спасибо за доверие к ScriptCat! Мы и дальше будем придерживаться принципа приоритета конфиденциальности и предоставлять вам безопасные и надёжные сервисы.
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/use/policy/privacy_website.md b/i18n/ru/docusaurus-plugin-content-docs/current/use/policy/privacy_website.md
new file mode 100644
index 00000000..987f4946
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/use/policy/privacy_website.md
@@ -0,0 +1,37 @@
+---
+title: Политика конфиденциальности сайта скриптов
+---
+
+Добро пожаловать. ScriptCat (включая сервисы приложения и сайта, далее — «продукты и сервисы») разрабатывается и управляется scriptcat.org (далее — «мы»). Безопасность данных и защита конфиденциальности пользователей — наш приоритет. Эта политика описывает, какие данные собираются при посещении и использовании продуктов и сервисов и как они обрабатываются.
+
+Перед продолжением использования внимательно прочитайте и подтвердите, что полностью понимаете правила и ключевые пункты этой Политики конфиденциальности. Выбирая использование, вы считаетесь согласными со всем содержанием Политики и с тем, что мы собираем и используем связанные сведения в соответствии с ней. Вопросы при чтении можно направлять в поддержку: yz@ggnb.top или через обратную связь в продукте. Если вы не согласны с соглашением или любым его условием, прекратите использование наших продуктов и сервисов.
+
+Эта политика помогает понять:
+
+1. как мы собираем и используем ваши персональные данные;
+2. как мы храним и защищаем ваши персональные данные;
+3. как мы передаём, уступаем и публично раскрываем ваши персональные данные;
+
+### 1. Как мы собираем и используем персональные данные
+
+Персональные данные — сведения в электронной или иной форме, которые сами по себе или вместе с другими данными позволяют идентифицировать физическое лицо или отражают его деятельность. Поскольку наши продукты и сервисы не требуют такой информации, мы сообщаем: **мы не собираем о вас персональные данные**.
+
+### 2. Как мы храним и защищаем персональные данные
+
+Как правило, мы храним персональные данные лишь столько, сколько необходимо для целей их сбора. Мы храним их ровно столько, сколько строго необходимо для управления нашими отношениями с вами (например, пока у вас открыт аккаунт и вы получаете услуги наших продуктов). Для исполнения юридических обязанностей либо подтверждения права или договора в пределах применимого срока исковой давности нам может потребоваться хранить архивные данные дольше указанных сроков; в таком случае мы не сможем удалить их по вашему запросу. Когда данные больше не нужны ни для этих целей, ни для обязательного архивного хранения или соблюдения сроков исковой давности, мы полностью удаляем или обезличиваем их.
+Мы применяем отраслевые меры безопасности для защиты предоставленных вами данных и шифруем ключевые данные, чтобы предотвратить несанкционированный доступ, раскрытие, использование, изменение, повреждение или утрату. Мы принимаем все разумные и осуществимые меры для защиты ваших персональных данных: шифрование для конфиденциальности; надёжные механизмы защиты от вредоносных атак.
+
+### 3. Как мы передаём, уступаем и публично раскрываем персональные данные
+
+Когда это нужно для повседневной деятельности и законных интересов по лучшему обслуживанию клиентов, мы используем персональные данные законно и уместно. С учётом бизнеса и иных аспектов мы используем эти данные только сами и **не передаём их третьим сторонам**.
+Мы можем раскрывать персональные данные вовне в соответствии с законами и обязательными требованиями госорганов. При получении такого запроса мы требуем соответствующие правовые документы (повестка, запрос на расследование и т.п.). Мы стремимся быть максимально прозрачными в рамках закона относительно запрашиваемой информации.
+В следующих случаях передача, уступка и публичное раскрытие персональных данных не требуют предварительного согласия:
+
+1. напрямую связаны с национальной безопасностью и обороной;
+2. напрямую связаны с уголовным расследованием, обвинением, судом и исполнением приговоров;
+3. для защиты жизни, имущества и иных существенных законных прав и интересов вас или других лиц, когда согласие лица получить затруднительно;
+4. персональные данные, которые вы сами раскрыли публично;
+5. сбор из законно раскрытых источников (официальные новости, раскрытие госинформации и т.п.);
+6. необходимо для заключения и исполнения договора по требованию субъекта персональных данных;
+7. необходимо для безопасной и стабильной работы продуктов или сервисов (например, обнаружение и устранение сбоев);
+8. иные случаи, предусмотренные законами и нормативными актами.
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/use/script_installation.md b/i18n/ru/docusaurus-plugin-content-docs/current/use/script_installation.md
new file mode 100644
index 00000000..67803a98
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/use/script_installation.md
@@ -0,0 +1,50 @@
+---
+title: Установка скриптов
+---
+
+> Сначала установите расширение ScriptCat по [Быстрому старту](/docs/use/use/).
+
+## Установка с различных сайтов
+
+### Сообщество ScriptCat
+
+[Сообщество ScriptCat](https://scriptcat.org/search) — официальный сайт ScriptCat
+
+### Userscript.Zone
+
+[Userscript.Zone](https://www.userscript.zone/) — сайт для поиска пользовательских скриптов по URL или домену.
+
+- **Большой объём скриптов**
+- **Легко найти подходящий скрипт**
+- **Показываются только скрипты с проверенных страниц или страниц с комментариями**
+
+### GreasyFork
+
+[GreasyFork](https://greasyfork.org/) — популярная платформа для размещения и обмена userscripts: разработчики публикуют, пользователи устанавливают скрипты, улучшающие или изменяющие сайты. Создан Jason Barnabe, известен акцентом на безопасность и открытость, большая коллекция скриптов.
+
+Jason Barnabe также создал расширение Stylish. Однако [Stylish](https://userstyles.org/) был продан в 2016 году и сейчас развивается другой компанией; Jason Barnabe к дальнейшей разработке не причастен.
+
+- **Большой объём скриптов**
+- **Синхронизация скриптов с Github**
+- **Активная модель open source**
+
+### OpenUserJS
+
+[OpenUserJS](https://openuserjs.org/) появился после GreasyFork. Создан Sizzle McTwizzle; в репозитории также много скриптов.
+
+- **Синхронизация с Github и форк скриптов**
+- **Активная модель open source**
+
+### GitHub/Gist
+
+Скрипты можно искать на Github и Gist.
+
+
+## Ручная установка скрипта
+
+1. Нажмите значок расширения ScriptCat
+2. Нажмите кнопку «шестерёнка», чтобы открыть интерфейс управления ScriptCat
+3. В правом верхнем углу нажмите «Создать новый скрипт» (обычно достаточно обычного скрипта)
+4. Вставьте код скрипта во всплывающей странице
+5. Сохраните изменения: `ctrl + s`
+6. Вернитесь в интерфейс управления — новый скрипт должен появиться в списке
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/use/sync.md b/i18n/ru/docusaurus-plugin-content-docs/current/use/sync.md
new file mode 100644
index 00000000..fc4bc1f3
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/use/sync.md
@@ -0,0 +1,17 @@
+---
+title: Синхронизация и резервное копирование
+---
+
+Поддерживаются следующие облачные хранилища:
+
+- [x] WebDAV
+- [x] Baidu NetDisk
+- [x] OneDrive
+- [x] Google Drive
+- [x] Dropbox
+
+## Синхронизация
+
+При обновлении скрипта изменения сразу синхронизируются в облако. Когда данные в облаке меняются, сканирование и синхронизация на локальное устройство занимают некоторое время. Учитывайте это, если несколько устройств используют одно облачное хранилище.
+
+Нажатие «Сохранить» в разделе синхронизации скриптов запускает полную синхронизацию сразу.
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/use/use.md b/i18n/ru/docusaurus-plugin-content-docs/current/use/use.md
new file mode 100644
index 00000000..608091d0
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/use/use.md
@@ -0,0 +1,85 @@
+---
+slug: /use/use
+title: Быстрый старт
+---
+
+ScriptCat — браузерное расширение для запуска пользовательских скриптов, совместимое со скриптами Tampermonkey и с дополнительными возможностями. Если вы нашли ошибку или хотите предложить улучшение, оставьте отзыв в [репозитории GitHub](https://github.com/scriptscat/scriptcat).
+
+## Установка расширения
+
+Установить расширение можно из следующих магазинов:
+
+| Браузер         | Ссылка                                                                                                                                                                                                                                     | Статус         |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
+| Chrome          | [Стабильная версия](https://chrome.google.com/webstore/detail/scriptcat/ndcooeababalnlpkfedmmbbbgkljhpjf) [Бета](https://chromewebstore.google.com/detail/%E8%84%9A%E6%9C%AC%E7%8C%AB-beta/jaehimmlecjmebpekkipmpmbpfhdacom?authuser=0&hl=zh-CN) | ✅ Доступно    |
+| Edge            | [Стабильная версия](https://microsoftedge.microsoft.com/addons/detail/scriptcat/liilgpjgabokdklappibcjfablkpcekh) [Бета](https://microsoftedge.microsoft.com/addons/detail/scriptcat-beta/nimmbghgpcjmeniofmpdfkofcedcjpfi)                      | ✅ Доступно    |
+| Firefox         | [Стабильная версия](https://addons.mozilla.org/zh-CN/firefox/addon/scriptcat/) [Бета](https://addons.mozilla.org/zh-CN/firefox/addon/scriptcat-pre/)                                                                                             | ✅ MV2         |
+
+### Другие браузеры
+
+Если вашего браузера нет в списке, скачайте файл `zip`/`crx` со страницы [Github Release](https://github.com/scriptscat/scriptcat/releases) и установите вручную.
+
+### Установка через загрузку распакованного расширения {#load-unpacked-extension-installation}
+
+① Скачайте файл `zip` со страницы [Github Release](https://github.com/scriptscat/scriptcat/releases) или [Community Download](https://bbs.tampermonkey.net.cn/thread-3068-1-1.html). Если это файл `crx`, переименуйте расширение в `zip`.
+
+② Подготовьте папку для хранения плагина и распакуйте zip в эту папку. После распаковки должно получиться примерно так (**важно: эту папку нельзя удалять или перемещать, иначе расширение перестанет работать**) ![download-zip](@site/i18n/en/docusaurus-plugin-content-docs/current/use/use.assets/download-zip.webp)
+
+③ Откройте страницу управления расширениями браузера и загрузите распакованное расширение (сначала включите режим разработчика — см. [Включение поддержки пользовательских скриптов](/docs/use/open-dev/))
+
+- 1. **Edge** ![edge-load-unpacked](@site/i18n/en/docusaurus-plugin-content-docs/current/use/use.assets/edge-load-unpacked.webp)
+- 2. **Chrome** ![chrome-load-unpacked](@site/i18n/en/docusaurus-plugin-content-docs/current/use/use.assets/chrome-load-unpacked.webp)
+
+④ Выберите папку, созданную на шаге ② (после загрузки в списке расширений появится значок ScriptCat; его также можно увидеть, нажав кнопку расширений справа от адресной строки)
+
+- 1. **Edge** ![edge-load-unpacked-img](@site/i18n/en/docusaurus-plugin-content-docs/current/use/use.assets/edge-load-unpacked-img.webp)
+- 2. **Chrome** ![chrome-load-unpacked-img](@site/i18n/en/docusaurus-plugin-content-docs/current/use/use.assets/chrome-load-unpacked-img.webp)
+
+⑤ Нажмите значок ScriptCat в правом верхнем углу, затем `┆` > «Получить скрипты» — откроется сайт скриптов, где можно искать и устанавливать скрипты.
+
+Примечание: расширения, установленные таким способом, не обновляются автоматически. Для обновления повторите шаги выше (замените файлы и перезагрузите расширение).
+
+
+## Где взять скрипты
+
+> Помимо скриптов, полезную информацию и руководства можно найти на [китайском форуме Tampermonkey](https://bbs.tampermonkey.net.cn/) и в [гайде по разработке скриптов](https://learn.scriptcat.org/).
+
+### Сайт скриптов ScriptCat
+
+[Сайт скриптов ScriptCat](https://scriptcat.org/) — официальный сайт расширения, где можно публиковать свои скрипты.
+
+- Новый сайт скриптов
+- Фоновые скрипты / скрипты по расписанию
+- Удобный интерфейс
+
+### Поиск Userscript.Zone
+
+[Userscript.Zone Search](https://www.userscript.zone/?utm_source=tm.net&utm_medium=scripts) — сайт, где можно искать пользовательские скрипты по URL или домену.
+
+- Большой объём скриптов
+- Легко найти подходящий скрипт
+- Показываются только скрипты с проверенных страниц или страниц с комментариями
+
+### GreasyFork
+
+[GreasyFork](https://greasyfork.org/) — популярная платформа для размещения и обмена userscripts: разработчики публикуют, пользователи устанавливают скрипты, улучшающие или изменяющие сайты. Создан Jason Barnabe, известен акцентом на безопасность и открытость, большая коллекция скриптов.
+
+Jason Barnabe также создал расширение Stylish. Однако [Stylish](https://userstyles.org/) был продан в 2016 году и сейчас развивается другой компанией; Jason Barnabe к дальнейшей разработке не причастен.
+
+- Большой объём скриптов
+- Синхронизация скриптов с Github
+- Активная [модель open source](https://github.com/JasonBarnabe/greasyfork)
+
+### GitHub/Gist
+
+Можно [искать скрипты на Github и Gist.](https://gist.github.com/search?l=JavaScript&o=desc&q="%3D%3DUserScript%3D%3D"&s=updated)
+
+## Обзор для новичков
+
+После установки ScriptCat при открытии панели управления автоматически запускается ознакомительный тур (его можно снова открыть в «Центре помощи» в левой боковой панели). Тур охватывает:
+
+- [Установку скриптов](/docs/use/script_installation/): из магазинов скриптов, включая [фоновые скрипты](/docs/dev/background/).
+- Управление: редактирование, запуск/остановка, [UserConfig](/docs/dev/config/).
+- [Резервное копирование](/docs/use/sync/) и [миграцию из других менеджеров](/docs/use/from-other/migrate-from-tampermonkey/).
+- [Синхронизацию скриптов](/docs/use/sync/).
+- [Подписки](/docs/dev/subscribe/).
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/use/vscode.md b/i18n/ru/docusaurus-plugin-content-docs/current/use/vscode.md
new file mode 100644
index 00000000..5af3c539
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/use/vscode.md
@@ -0,0 +1,67 @@
+---
+title: Разработка скриптов в VSCode
+---
+
+ScriptCat предоставляет расширение для VSCode, чтобы писать пользовательские скрипты прямо в редакторе. После сохранения изменения автоматически синхронизируются в ScriptCat в браузере — без ручного копирования, что сильно ускоряет разработку.
+
+## Требования
+
+Нужно установить два инструмента:
+
+1. **Расширение ScriptCat в браузере** — если ещё не установлено, следуйте [Быстрому старту](/docs/use/use/)
+2. **Расширение ScriptCat в VSCode** — найдите «[scriptcat-vscode](https://marketplace.visualstudio.com/items?itemName=CodFrm.scriptcat-vscode)» в Marketplace VSCode или скачайте из [репозитория GitHub](https://github.com/scriptscat/scriptcat-vscode)
+
+## Подключение
+
+После установки нужно связать расширение ScriptCat в браузере с VSCode:
+
+1. Нажмите значок ScriptCat в браузере, чтобы открыть панель управления
+2. Перейдите в **Инструменты > Инструменты разработчика**
+3. Найдите **Автоподключение к службе VSCode**, включите и нажмите **Подключить**
+
+После подключения между VSCode и ScriptCat устанавливается канал в реальном времени.
+
+## Синхронизация скриптов
+
+После подключения можно выбрать один из двух способов:
+
+### Вариант 1: автоопределение (рекомендуется)
+
+1. В VSCode нажмите `Ctrl + Shift + P` (`Cmd + Shift + P` на Mac), чтобы открыть палитру команд
+2. Введите и выберите `scriptcat.autoTarget`
+3. Далее при открытии или сохранении файла `.user.js` он автоматически синхронизируется в ScriptCat
+
+### Вариант 2: указанный скрипт
+
+1. В VSCode нажмите `Ctrl + Shift + P` (`Cmd + Shift + P` на Mac)
+2. Введите и выберите `scriptcat.target`
+3. Укажите путь к файлу скрипта для синхронизации
+
+## Рабочий процесс
+
+После настройки процесс простой:
+
+1. Пишите или редактируйте `.user.js` в VSCode
+2. Сохраните файл (`Ctrl + S`)
+3. Скрипт автоматически синхронизируется в ScriptCat в браузере
+4. Переключитесь в браузер и обновите страницу, чтобы увидеть результат
+
+Ручных шагов не требуется — сохранение сразу вступает в силу.
+
+## FAQ
+
+### Не подключается?
+
+- Убедитесь, что расширение ScriptCat в браузере запущено
+- Убедитесь, что расширение ScriptCat в VSCode установлено и включено
+- Проверьте статус подключения на странице «Инструменты разработчика» в панели ScriptCat
+
+### После сохранения скрипт не обновляется?
+
+- Убедитесь, что имя файла заканчивается на `.user.js`
+- Убедитесь, что выполняли команду `scriptcat.autoTarget` или `scriptcat.target`
+- Проверьте панель вывода VSCode на ошибки
+
+### Нужно ли переподключаться после перезапуска VSCode?
+
+Если включено «Автоподключение к службе VSCode», после перезапуска VSCode переподключится сам — вручную ничего делать не нужно.
diff --git a/i18n/ru/docusaurus-theme-classic/footer.json b/i18n/ru/docusaurus-theme-classic/footer.json
new file mode 100644
index 00000000..c53a06e1
--- /dev/null
+++ b/i18n/ru/docusaurus-theme-classic/footer.json
@@ -0,0 +1,34 @@
+{
+  "link.title.Docs": {
+    "message": "Документация",
+    "description": "The title of the footer links column with title=Docs in the footer"
+  },
+  "link.item.label.使用指南": {
+    "message": "Руководство пользователя",
+    "description": "The label of footer link with label=使用指南 linking to /docs/use"
+  },
+  "link.item.label.开发指南": {
+    "message": "Руководство разработчика",
+    "description": "The label of footer link with label=开发指南 linking to /docs/dev"
+  },
+  "link.title.Community": {
+    "message": "Сообщество",
+    "description": "The title of the footer links column with title=Community in the footer"
+  },
+  "link.item.label.油猴中文网": {
+    "message": "Китайский форум Tampermonkey",
+    "description": "The label of footer link with label=油猴中文网 linking to https://bbs.tampermonkey.net.cn/"
+  },
+  "link.item.label.脚本猫脚本站": {
+    "message": "Магазин скриптов ScriptCat",
+    "description": "The label of footer link with label=脚本猫脚本站 linking to https://scriptcat.org/"
+  },
+  "link.title.More": {
+    "message": "Ещё",
+    "description": "The title of the footer links column with title=More in the footer"
+  },
+  "copyright": {
+    "message": "Copyright © {year} ScriptCat, Inc. Built with Docusaurus.",
+    "description": "The footer copyright"
+  }
+}
diff --git a/i18n/ru/docusaurus-theme-classic/navbar.json b/i18n/ru/docusaurus-theme-classic/navbar.json
new file mode 100644
index 00000000..0bc5596e
--- /dev/null
+++ b/i18n/ru/docusaurus-theme-classic/navbar.json
@@ -0,0 +1,18 @@
+{
+  "item.label.使用文档": {
+    "message": "Руководство",
+    "description": "The label for the user guide navbar item"
+  },
+  "item.label.开发文档": {
+    "message": "Документация для разработчиков",
+    "description": "The label for the developer guide navbar item"
+  },
+  "item.label.更新日志": {
+    "message": "История изменений",
+    "description": "The label for the changelog navbar item"
+  },
+  "item.label.脚本开发指南": {
+    "message": "Гайд по разработке скриптов",
+    "description": "The label for the script development guide navbar item"
+  }
+}
diff --git a/i18n/zh-Hans/code.json b/i18n/zh-Hans/code.json
index 244d4c74..2b604550 100644
--- a/i18n/zh-Hans/code.json
+++ b/i18n/zh-Hans/code.json
@@ -249,6 +249,10 @@
   "homepage.meta.description": {
     "message": "脚本猫是一个强大的用户脚本管理器，轻松定制网页、消除广告、自动执行任务等，激活浏览器的无限可能！"
   },
+  "homepage.meta.keywords": {
+    "message": "ScriptCat,脚本猫,用户脚本,浏览器扩展,userscript,Tampermonkey,Violentmonkey,后台脚本,定时脚本,浏览器自动化,广告屏蔽,脚本商店",
+    "description": "Homepage SEO keywords"
+  },
   "homepage.meta.title": {
     "message": "首页"
   },
@@ -870,6 +874,18 @@
     "message": "如果您改变主意，可以随时重新安装：",
     "description": "Reinstall message"
   },
+  "uninstall.reinstall.chrome": {
+    "message": "Chrome 商店",
+    "description": "Reinstall from Chrome Web Store button"
+  },
+  "uninstall.reinstall.edge": {
+    "message": "Edge 商店",
+    "description": "Reinstall from Edge Add-ons button"
+  },
+  "uninstall.reinstall.firefox": {
+    "message": "Firefox 商店",
+    "description": "Reinstall from Firefox Add-ons button"
+  },
   "uninstall.thanks.considerReinstall": {
     "message": "如果您改变主意，随时欢迎回来",
     "description": "Consider reinstall message"
diff --git a/package.json b/package.json
index 3f090b42..be3fc545 100644
--- a/package.json
+++ b/package.json
@@ -7,6 +7,7 @@
     "start": "docusaurus start",
     "start:zh": "docusaurus start --locale zh-Hans",
     "start:en": "docusaurus start --locale en --port 3001",
+    "start:ru": "docusaurus start --locale ru --port 3002",
     "prebuild": "node scripts/fetch-landing-stats.mjs || true",
     "build": "docusaurus build",
     "swizzle": "docusaurus swizzle",
@@ -17,9 +18,10 @@
     "write-heading-ids": "docusaurus write-heading-ids",
     "typecheck": "tsc",
     "check:urls": "node scripts/check-url-inventory.mjs",
+    "check:fallbacks": "node scripts/check-i18n-fallbacks.mjs",
     "check:i18n": "node scripts/check-i18n-parity.mjs",
     "check:frontmatter": "node scripts/check-frontmatter.mjs",
-    "check": "npm run check:urls && npm run check:i18n && npm run check:frontmatter"
+    "check": "npm run check:urls && npm run check:fallbacks && npm run check:i18n && npm run check:frontmatter"
   },
   "dependencies": {
     "@ant-design/icons": "^5.1.4",
diff --git a/scripts/check-config.json b/scripts/check-config.json
index 763a3873..f2d5db21 100644
--- a/scripts/check-config.json
+++ b/scripts/check-config.json
@@ -1,4 +1,11 @@
 {
+  "defaultLocale": "zh-Hans",
   "i18nParityStrict": true,
-  "frontmatterStrict": true
+  "frontmatterStrict": true,
+  "i18nDocFallbacks": {
+    "ru": {
+      "sourceLocale": "en",
+      "paths": ["change/"]
+    }
+  }
 }
diff --git a/scripts/check-frontmatter.mjs b/scripts/check-frontmatter.mjs
index 4ced960e..f6079a58 100644
--- a/scripts/check-frontmatter.mjs
+++ b/scripts/check-frontmatter.mjs
@@ -12,9 +12,13 @@ import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
 import { join, relative, sep, basename } from "node:path";
 
 const ROOT = new URL("..", import.meta.url).pathname;
+const I18N_DIR = join(ROOT, "i18n");
+const DOCS_PLUGIN_PATH = "docusaurus-plugin-content-docs/current";
 const DOC_DIRS = [
   join(ROOT, "docs"),
-  join(ROOT, "i18n/en/docusaurus-plugin-content-docs/current"),
+  ...readdirSync(I18N_DIR)
+    .map((locale) => join(I18N_DIR, locale, DOCS_PLUGIN_PATH))
+    .filter((dir) => existsSync(dir) && statSync(dir).isDirectory()),
 ];
 const CONFIG_FILE = join(ROOT, "scripts", "check-config.json");
 const NUMBER_PREFIX = /^\d+\.[^/]/;
diff --git a/scripts/check-i18n-fallbacks.mjs b/scripts/check-i18n-fallbacks.mjs
new file mode 100644
index 00000000..43bbb389
--- /dev/null
+++ b/scripts/check-i18n-fallbacks.mjs
@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// Verifies configured single-source doc fallbacks in the production build.
+// The localized page's edit URL must point to the configured source locale,
+// proving that Docusaurus compiled that source instead of its default locale.
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { extname, join, relative, sep } from "node:path";
+
+const ROOT = new URL("..", import.meta.url).pathname;
+const BUILD_DIR = join(ROOT, "build");
+const I18N_DIR = join(ROOT, "i18n");
+const DOCS_PLUGIN_PATH = "docusaurus-plugin-content-docs/current";
+const CONFIG_FILE = join(ROOT, "scripts", "check-config.json");
+
+function listFiles(dir, predicate) {
+  const results = [];
+  function recurse(current) {
+    for (const entry of readdirSync(current)) {
+      const full = join(current, entry);
+      if (statSync(full).isDirectory()) recurse(full);
+      else if (predicate(full)) results.push(full);
+    }
+  }
+  if (existsSync(dir)) recurse(dir);
+  return results;
+}
+
+function relativePath(base, file) {
+  return relative(base, file).split(sep).join("/");
+}
+
+function main() {
+  if (!existsSync(BUILD_DIR)) {
+    console.error("build/ not found — run `pnpm run build` first.");
+    process.exit(1);
+  }
+
+  const config = JSON.parse(readFileSync(CONFIG_FILE, "utf8"));
+  const fallbacks = config.i18nDocFallbacks ?? {};
+  let checked = 0;
+  const issues = [];
+
+  for (const [locale, fallback] of Object.entries(fallbacks)) {
+    const sourceRoot = join(I18N_DIR, fallback.sourceLocale, DOCS_PLUGIN_PATH);
+    const localeRoot = join(I18N_DIR, locale, DOCS_PLUGIN_PATH);
+    const builtDocsRoot = join(BUILD_DIR, locale, "docs");
+    const builtPages = listFiles(builtDocsRoot, (file) => file.endsWith("index.html")).map(
+      (file) => ({ file, html: readFileSync(file, "utf8") })
+    );
+
+    if (!existsSync(sourceRoot)) {
+      issues.push(`${locale}: fallback source locale ${fallback.sourceLocale} has no docs tree`);
+      continue;
+    }
+
+    const fallbackDocs = listFiles(sourceRoot, (file) => [".md", ".mdx"].includes(extname(file)))
+      .map((file) => relativePath(sourceRoot, file))
+      .filter(
+        (doc) =>
+          fallback.paths.some((prefix) => doc.startsWith(prefix)) &&
+          !existsSync(join(localeRoot, doc))
+      );
+
+    for (const doc of fallbackDocs) {
+      const editPath =
+        `edit/main/i18n/${fallback.sourceLocale}/${DOCS_PLUGIN_PATH}/${doc}`;
+      const matches = builtPages.filter(({ html }) => html.includes(editPath));
+      if (matches.length !== 1) {
+        issues.push(
+          `${locale}:${doc}: expected one built page sourced from ${fallback.sourceLocale}, found ${matches.length}`
+        );
+      } else {
+        checked += 1;
+      }
+    }
+  }
+
+  if (issues.length > 0) {
+    console.error(`i18n fallback build check FAILED (${issues.length}):`);
+    for (const issue of issues) console.error(`  - ${issue}`);
+    process.exit(1);
+  }
+
+  console.log(`i18n fallback build check passed: ${checked} localized pages use configured sources.`);
+}
+
+main();
diff --git a/scripts/check-i18n-parity.mjs b/scripts/check-i18n-parity.mjs
index f8114b0b..cc8432da 100644
--- a/scripts/check-i18n-parity.mjs
+++ b/scripts/check-i18n-parity.mjs
@@ -1,8 +1,12 @@
 #!/usr/bin/env node
-// Verifies every zh-Hans doc under docs/ has an English mirror under
-// i18n/en/docusaurus-plugin-content-docs/current/ (and vice versa).
+// Verifies every default-locale doc under docs/ has a mirror in every locale
+// docs tree under i18n/ (and vice versa).
 //
 // Controlled by scripts/check-config.json: { "i18nParityStrict": boolean }.
+// Intentional single-source fallbacks can be declared with:
+//   { "i18nDocFallbacks": { "ru": {
+//       "sourceLocale": "en", "paths": ["change/"]
+//   } } }
 // While false, mismatches are printed as warnings and the script exits 0.
 // Once the translation backlog is cleared, flip it to true to hard-fail CI.
 
@@ -10,8 +14,9 @@ import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
 import { join, relative, sep } from "node:path";
 
 const ROOT = new URL("..", import.meta.url).pathname;
-const ZH_DIR = join(ROOT, "docs");
-const EN_DIR = join(ROOT, "i18n/en/docusaurus-plugin-content-docs/current");
+const DEFAULT_DIR = join(ROOT, "docs");
+const I18N_DIR = join(ROOT, "i18n");
+const DOCS_PLUGIN_PATH = "docusaurus-plugin-content-docs/current";
 const CONFIG_FILE = join(ROOT, "scripts", "check-config.json");
 
 // Node 18/20 (the CI runtime) lack fs.globSync (added in Node 22), so walk manually.
@@ -35,27 +40,77 @@ function listDocs(dir) {
 function main() {
   const config = JSON.parse(readFileSync(CONFIG_FILE, "utf8"));
   const strict = Boolean(config.i18nParityStrict);
+  const defaultLocale = config.defaultLocale;
+  const fallbacks = config.i18nDocFallbacks ?? {};
 
-  const zhDocs = listDocs(ZH_DIR);
-  const enDocs = existsSync(EN_DIR) ? listDocs(EN_DIR) : [];
-  const enSet = new Set(enDocs);
-  const zhSet = new Set(zhDocs);
+  if (!defaultLocale) {
+    console.error("scripts/check-config.json must define defaultLocale.");
+    process.exit(1);
+  }
 
-  const missing = zhDocs.filter((d) => !enSet.has(d));
-  const orphans = enDocs.filter((d) => !zhSet.has(d));
+  const defaultDocs = listDocs(DEFAULT_DIR);
+  const defaultSet = new Set(defaultDocs);
+  const localeDirs = readdirSync(I18N_DIR)
+    .filter(
+      (locale) =>
+        locale !== defaultLocale && statSync(join(I18N_DIR, locale)).isDirectory()
+    )
+    .map((locale) => ({
+      locale,
+      dir: join(I18N_DIR, locale, DOCS_PLUGIN_PATH),
+    }))
+    .sort((a, b) => a.locale.localeCompare(b.locale));
 
-  if (missing.length === 0 && orphans.length === 0) {
-    console.log(`i18n parity check passed: ${zhDocs.length} docs, all translated.`);
-    return;
+  if (localeDirs.length === 0) {
+    console.error("No localized docs trees found under i18n/.");
+    process.exit(1);
   }
 
-  if (missing.length > 0) {
-    console.log(`Missing English translation (${missing.length}):`);
-    for (const m of missing) console.log(`  - ${m}`);
+  let issueCount = 0;
+  const summaries = [];
+
+  for (const { locale, dir } of localeDirs) {
+    const localeDocs = existsSync(dir) ? listDocs(dir) : [];
+    const localeSet = new Set(localeDocs);
+    const fallback = fallbacks[locale];
+    const fallbackPaths = fallback?.paths ?? [];
+    const fallbackDir = fallback?.sourceLocale
+      ? join(I18N_DIR, fallback.sourceLocale, DOCS_PLUGIN_PATH)
+      : undefined;
+    const fallbackSet =
+      fallbackDir && existsSync(fallbackDir) ? new Set(listDocs(fallbackDir)) : new Set();
+
+    const missing = defaultDocs.filter((doc) => !localeSet.has(doc));
+    const fallbackDocs = missing.filter(
+      (doc) => fallbackPaths.some((prefix) => doc.startsWith(prefix)) && fallbackSet.has(doc)
+    );
+    const fallbackDocSet = new Set(fallbackDocs);
+    const unexpectedMissing = missing.filter((doc) => !fallbackDocSet.has(doc));
+    const orphans = localeDocs.filter((doc) => !defaultSet.has(doc));
+
+    if (unexpectedMissing.length > 0) {
+      console.log(`Missing ${locale} translation (${unexpectedMissing.length}):`);
+      for (const doc of unexpectedMissing) console.log(`  - ${doc}`);
+    }
+    if (orphans.length > 0) {
+      console.log(`${locale} doc with no default-locale source (${orphans.length}):`);
+      for (const doc of orphans) console.log(`  - ${doc}`);
+    }
+    if (fallbackDocs.length > 0) {
+      console.log(
+        `${locale}: ${fallbackDocs.length} docs intentionally fall back to ${fallback.sourceLocale}.`
+      );
+    }
+
+    issueCount += unexpectedMissing.length + orphans.length;
+    summaries.push(`${locale}: ${localeDocs.length} translated, ${fallbackDocs.length} fallback`);
   }
-  if (orphans.length > 0) {
-    console.log(`English doc with no zh-Hans source (${orphans.length}):`);
-    for (const o of orphans) console.log(`  - ${o}`);
+
+  if (issueCount === 0) {
+    console.log(
+      `i18n parity check passed: ${defaultDocs.length} default-locale docs; ${summaries.join("; ")}.`
+    );
+    return;
   }
 
   if (strict) {
diff --git a/scripts/url-inventory.txt b/scripts/url-inventory.txt
index fa5b1f71..05c9f627 100644
--- a/scripts/url-inventory.txt
+++ b/scripts/url-inventory.txt
@@ -94,5 +94,54 @@
 /en/uninstall/index.html
 /index.html
 /opensearch.xml
+/ru/404.html
+/ru/docs/about/index.html
+/ru/docs/change/beta-changelog/index.html
+/ru/docs/change/index.html
+/ru/docs/change/v0.16/index.html
+/ru/docs/change/v0.17/index.html
+/ru/docs/change/v1.1/index.html
+/ru/docs/change/v1.2/index.html
+/ru/docs/change/v1.3/index.html
+/ru/docs/change/v1.4/index.html
+/ru/docs/change/v1.5/index.html
+/ru/docs/dev/agent/agent-builtin-tools/index.html
+/ru/docs/dev/agent/agent-conversation/index.html
+/ru/docs/dev/agent/agent-dom/index.html
+/ru/docs/dev/agent/agent-mcp/index.html
+/ru/docs/dev/agent/agent-model/index.html
+/ru/docs/dev/agent/agent-opfs/index.html
+/ru/docs/dev/agent/agent-skill-dev/index.html
+/ru/docs/dev/agent/agent-skill-install/index.html
+/ru/docs/dev/agent/agent-skill/index.html
+/ru/docs/dev/agent/agent-task/index.html
+/ru/docs/dev/agent/index.html
+/ru/docs/dev/api/index.html
+/ru/docs/dev/background/index.html
+/ru/docs/dev/cat-api/index.html
+/ru/docs/dev/cloudcat/index.html
+/ru/docs/dev/config/index.html
+/ru/docs/dev/index.html
+/ru/docs/dev/meta/index.html
+/ru/docs/dev/subscribe/index.html
+/ru/docs/script_installation/index.html
+/ru/docs/sponsor/index.html
+/ru/docs/use/QA/index.html
+/ru/docs/use/from-other/migrate-from-tampermonkey/index.html
+/ru/docs/use/from-other/migrate-from-violentmonkey/index.html
+/ru/docs/use/index.html
+/ru/docs/use/install_comple/index.html
+/ru/docs/use/open-dev/index.html
+/ru/docs/use/policy/disclaimer/index.html
+/ru/docs/use/policy/privacy/index.html
+/ru/docs/use/policy/privacy_website/index.html
+/ru/docs/use/script_installation/index.html
+/ru/docs/use/sync/index.html
+/ru/docs/use/use/index.html
+/ru/docs/use/vscode/index.html
+/ru/index.html
+/ru/opensearch.xml
+/ru/search/index.html
+/ru/uninstall/index.html
 /search/index.html
 /uninstall/index.html
diff --git a/src/components/landing/LandingNav.tsx b/src/components/landing/LandingNav.tsx
index f896a9b9..a48776cc 100644
--- a/src/components/landing/LandingNav.tsx
+++ b/src/components/landing/LandingNav.tsx
@@ -4,7 +4,7 @@ import { Dropdown } from "antd";
 import type { MenuProps } from "antd";
 import Translate, { translate } from "@docusaurus/Translate";
 import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
-import useBaseUrl from "@docusaurus/useBaseUrl";
+import useBaseUrl, { useBaseUrlUtils } from "@docusaurus/useBaseUrl";
 import { useTheme } from "../useTheme";
 import styles from "./landing.module.css";
 import stats from "@site/src/data/landing-stats.json";
@@ -14,17 +14,22 @@ import { LINKS, abbr, usePrimaryInstall } from "./shared";
 // Docusaurus navbar is hidden on the homepage (see custom.css) so this one
 // takes its place; docs pages keep the standard navbar.
 export function LandingNav() {
-  const { i18n } = useDocusaurusContext();
-  const zh = i18n.currentLocale !== "en";
   const [open, setOpen] = useState(false);
   const logo = useBaseUrl("/img/logo.png");
-  const home = zh ? "/" : "/en/";
+  // These are plain <a> (not <Link>), so baseUrl — which carries the active
+  // locale, e.g. /ru/ — has to be applied by hand. withBaseUrl leaves the
+  // absolute store/GitHub URLs untouched.
+  const { withBaseUrl } = useBaseUrlUtils();
+  const home = useBaseUrl("/");
 
   const menu = [
-    { label: <Translate id="home.nav.docs">文档</Translate>, href: LINKS.docs },
+    { label: <Translate id="home.nav.docs">文档</Translate>, href: withBaseUrl(LINKS.docs) },
     { label: <Translate id="home.nav.store">脚本商店</Translate>, href: LINKS.store },
-    { label: <Translate id="home.nav.dev">开发者</Translate>, href: LINKS.dev },
-    { label: <Translate id="home.nav.changelog">更新日志</Translate>, href: LINKS.changelog },
+    { label: <Translate id="home.nav.dev">开发者</Translate>, href: withBaseUrl(LINKS.dev) },
+    {
+      label: <Translate id="home.nav.changelog">更新日志</Translate>,
+      href: withBaseUrl(LINKS.changelog),
+    },
   ];
 
   return (
@@ -45,7 +50,7 @@ export function LandingNav() {
 
         <div className={styles.lnavActions}>
           <ThemeToggle />
-          <LangSwitch zh={zh} homeZh="/" />
+          <LangSwitch />
           <a
             className={styles.lnavStar}
             href={LINKS.github}
@@ -143,30 +148,39 @@ function ThemeToggle() {
   );
 }
 
-function LangSwitch({ zh, homeZh }: { zh: boolean; homeZh: string }) {
-  const items: MenuProps["items"] = [
-    {
-      key: "zh",
-      label: (
-        <a className={styles.lnavLangItem} href={homeZh}>
-          简体中文
-        </a>
-      ),
-    },
-    {
-      key: "en",
-      label: (
-        <a className={styles.lnavLangItem} href="/en/">
-          English
-        </a>
-      ),
-    },
-  ];
+// The locale list and its labels come straight from docusaurus.config.js
+// (i18n.locales / i18n.localeConfigs), so adding a locale there is enough —
+// nothing to update here. LandingNav only renders on the homepage, so each
+// entry points at that locale's home rather than the translated current page.
+function LangSwitch() {
+  const { i18n, siteConfig } = useDocusaurusContext();
+  const { currentLocale, defaultLocale, locales, localeConfigs } = i18n;
+  // siteConfig.baseUrl already carries the active locale (e.g. "/ru/"); strip
+  // that back off to recover the site root and build the other homes from it.
+  const currentPath = localeConfigs[currentLocale].path;
+  const siteRoot =
+    currentLocale === defaultLocale
+      ? siteConfig.baseUrl
+      : siteConfig.baseUrl.slice(0, -(currentPath.length + 1));
+
+  const items: MenuProps["items"] = locales.map((locale) => ({
+    key: locale,
+    label: (
+      <a
+        className={styles.lnavLangItem}
+        href={locale === defaultLocale ? siteRoot : `${siteRoot}${localeConfigs[locale].path}/`}
+        lang={localeConfigs[locale].htmlLang}
+      >
+        {localeConfigs[locale].label}
+      </a>
+    ),
+  }));
+
   return (
     <Dropdown menu={{ items }} trigger={["hover", "click"]} placement="bottomRight">
       <button className={styles.lnavLang}>
         <Icon icon="lucide:globe" width={16} height={16} />
-        <span>{zh ? "简体中文" : "English"}</span>
+        <span>{localeConfigs[currentLocale].label}</span>
         <Icon icon="lucide:chevron-down" width={14} height={14} />
       </button>
     </Dropdown>
diff --git a/src/components/landing/sections.tsx b/src/components/landing/sections.tsx
index 326d0be3..f5ac6575 100644
--- a/src/components/landing/sections.tsx
+++ b/src/components/landing/sections.tsx
@@ -1,6 +1,6 @@
 import { Icon } from "@iconify/react";
 import Link from "@docusaurus/Link";
-import Translate from "@docusaurus/Translate";
+import Translate, { translate } from "@docusaurus/Translate";
 import styles from "./landing.module.css";
 import stats from "@site/src/data/landing-stats.json";
 import {
@@ -538,7 +538,9 @@ export function Features() {
                 </div>
                 <div className={styles.codeBody}>
                   <div className={styles.codeComment}>{"// ==UserScript=="}</div>
-                  <div className={styles.codeMeta}>{"// @name    视频倍速控制"}</div>
+                  <div className={styles.codeMeta}>
+                    {`// @name    ${translate({ id: "home.hero.mock.speed", message: "视频倍速控制" })}`}
+                  </div>
                   <div className={styles.codeMeta}>{"// @match   *://*.bilibili.com/*"}</div>
                   <div className={styles.codeGrant}>{"// @grant   GM_setValue"}</div>
                   <div className={styles.codeComment}>{"// ==/UserScript=="}</div>
@@ -670,7 +672,9 @@ export function Developers() {
             </div>
             <div className={styles.editorCode}>
               <div className={styles.cComment}>{"// ==UserScript=="}</div>
-              <div className={styles.cMeta}>{"// @name  每日自动签到"}</div>
+              <div className={styles.cMeta}>
+                {`// @name  ${translate({ id: "home.dev.mock.name", message: "每日自动签到" })}`}
+              </div>
               <div className={styles.cMeta}>{"// @cron  0 9 * * *"}</div>
               <div className={styles.cComment}>{"// ==/UserScript=="}</div>
               <div>&nbsp;</div>
@@ -688,7 +692,9 @@ export function Developers() {
               </div>
               <div>
                 &nbsp;&nbsp;<span className={styles.cApi}>GM_notification</span>
-                <span className={styles.cStr}>('签到成功')</span>
+                <span className={styles.cStr}>
+                  {`('${translate({ id: "home.dev.mock.toast", message: "签到成功" })}')`}
+                </span>
               </div>
               <div className={styles.cPlain}>{"}"}</div>
               <div>&nbsp;</div>
@@ -700,7 +706,9 @@ export function Developers() {
           </div>
           <div className={styles.editorConsole}>
             <Logo size={15} />
-            <span>ScriptCat › 签到成功 · 200 OK</span>
+            <span>
+              {`ScriptCat › ${translate({ id: "home.dev.mock.toast", message: "签到成功" })} · 200 OK`}
+            </span>
           </div>
         </div>
       </div>
diff --git a/src/components/landing/shared.tsx b/src/components/landing/shared.tsx
index 4beefe7c..806bfd27 100644
--- a/src/components/landing/shared.tsx
+++ b/src/components/landing/shared.tsx
@@ -104,10 +104,13 @@ export function usePrimaryInstall(): {
 } {
   const target = useInstallTarget();
   const store = target === "unknown" ? null : STORES[target];
+  // Callers render this as a plain <a>, so the internal fallback needs baseUrl
+  // (which carries the active locale) applied here.
+  const guide = useBaseUrl(LINKS.docs);
   return {
     target,
     store,
-    href: store ? store.href : LINKS.docs,
+    href: store ? store.href : guide,
     external: store !== null,
   };
 }
diff --git a/src/pages/index.tsx b/src/pages/index.tsx
index 5734e5e6..1c41643c 100644
--- a/src/pages/index.tsx
+++ b/src/pages/index.tsx
@@ -23,7 +23,11 @@ export default function Home(): JSX.Element {
         <body className="landing-page" />
         <meta
           name="keywords"
-          content="ScriptCat,脚本猫,用户脚本,浏览器扩展,userscript,tampermonkey,violentmonkey,后台脚本,自动化,广告屏蔽,脚本商店"
+          content={translate({
+            id: "homepage.meta.keywords",
+            message:
+              "ScriptCat,脚本猫,用户脚本,浏览器扩展,userscript,tampermonkey,violentmonkey,后台脚本,自动化,广告屏蔽,脚本商店",
+          })}
         />
       </Head>
       <Layout
diff --git a/src/pages/uninstall.tsx b/src/pages/uninstall.tsx
index 6fa8b7fb..31a0ec99 100644
--- a/src/pages/uninstall.tsx
+++ b/src/pages/uninstall.tsx
@@ -32,6 +32,8 @@ import {
 } from "@ant-design/icons";
 import { Icon } from "@iconify/react";
 import Translate, { translate } from "@docusaurus/Translate";
+import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
+import { useBaseUrlUtils } from "@docusaurus/useBaseUrl";
 import { useTheme } from "../components/useTheme";
 import { submitFeedback, type FeedbackRequest, type FeedbackReason } from "../service/system";
 
@@ -90,17 +92,20 @@ export default function Uninstall(): JSX.Element {
   const [submitted, setSubmitted] = useState<boolean>(false);
   const { theme } = useTheme();
 
-  // 检测当前语言环境
-  const isEnglish = typeof window !== 'undefined' && window.location.pathname.startsWith('/en/');
+  // 检测当前语言环境。用 currentLocale 而不是判断路径前缀，否则 /ru/ 会被当成中文
+  const { i18n } = useDocusaurusContext();
+  const { withBaseUrl } = useBaseUrlUtils();
+  // 上游仓库只有中英两套 issue 模板，所以非中文语言统一走英文模板
+  const useEnglishTemplate = i18n.currentLocale !== i18n.defaultLocale;
 
   // 根据语言和反馈类型获取GitHub链接
   const getGithubUrl = (reason: FeedbackReason) => {
     if (reason === 'bug') {
-      return isEnglish 
+      return useEnglishTemplate
         ? 'https://github.com/scriptscat/scriptcat/issues/new?template=bug_report_en.yaml'
         : 'https://github.com/scriptscat/scriptcat/issues/new?template=bug_report.yaml';
     } else if (reason === 'feature') {
-      return isEnglish
+      return useEnglishTemplate
         ? 'https://github.com/scriptscat/scriptcat/issues/new?template=feature_request_en.md'
         : 'https://github.com/scriptscat/scriptcat/issues/new?template=feature_request.md';
     }
@@ -208,7 +213,7 @@ export default function Uninstall(): JSX.Element {
                       type="primary"
                       size="large"
                       icon={<HomeOutlined />}
-                      href="/"
+                      href={withBaseUrl("/")}
                       block
                       className="h-12 rounded-lg shadow-md hover:shadow-lg transition-all duration-200"
                     >
@@ -557,7 +562,9 @@ export default function Uninstall(): JSX.Element {
                         block
                         className="rounded-lg"
                       >
-                        Chrome 商店
+                        <Translate id="uninstall.reinstall.chrome">
+                          Chrome 商店
+                        </Translate>
                       </Button>
                       <Button
                         icon={<Icon icon="logos:microsoft-edge" />}
@@ -566,16 +573,20 @@ export default function Uninstall(): JSX.Element {
                         block
                         className="rounded-lg"
                       >
-                        Edge 商店
+                        <Translate id="uninstall.reinstall.edge">
+                          Edge 商店
+                        </Translate>
                       </Button>
                       <Button
                         icon={<Icon icon="logos:firefox" />}
-                        href="https://addons.mozilla.org/zh-CN/firefox/addon/scriptcat/"
+                        href="https://addons.mozilla.org/firefox/addon/scriptcat/"
                         target="_blank"
                         block
                         className="rounded-lg"
                       >
-                        Firefox 商店
+                        <Translate id="uninstall.reinstall.firefox">
+                          Firefox 商店
+                        </Translate>
                       </Button>
                     </Space>
                   </Card>
@@ -616,7 +627,7 @@ export default function Uninstall(): JSX.Element {
                       </Button>
                       <Button
                         icon={<MessageOutlined />}
-                        href="/docs"
+                        href={withBaseUrl("/docs")}
                         block
                         className="rounded-lg"
                       >
diff --git a/src/theme/Footer/index.tsx b/src/theme/Footer/index.tsx
index f4c77a67..3dd1a42d 100644
--- a/src/theme/Footer/index.tsx
+++ b/src/theme/Footer/index.tsx
@@ -3,8 +3,13 @@ import styles from "./index.module.css";
 import { IconCat } from "../../components/IconCat";
 import { Icon } from "@iconify/react";
 import Translate from '@docusaurus/Translate';
+import { useBaseUrlUtils } from "@docusaurus/useBaseUrl";
 
 function CustomFooter() {
+  // 内部链接是原生 <a>，需要手动补上带当前语言的 baseUrl（如 /ru/），
+  // 否则俄语/英文页面的页脚会把用户带回中文文档
+  const { withBaseUrl } = useBaseUrlUtils();
+
   return (
     <footer className={styles.footer}>
       <div className="container">
@@ -59,7 +64,7 @@ function CustomFooter() {
             </h4>
             <ul className={styles.footerColumnList}>
               <li>
-                <a href="/docs/use/use/" className={styles.footerColumnLink}>
+                <a href={withBaseUrl("/docs/use/use/")} className={styles.footerColumnLink}>
                   <Translate
                     id="footer.product.features"
                     description="Footer product features link"
@@ -83,7 +88,7 @@ function CustomFooter() {
                 </a>
               </li>
               <li>
-                <a href="/docs/change/" className={styles.footerColumnLink}>
+                <a href={withBaseUrl("/docs/change/")} className={styles.footerColumnLink}>
                   <Translate
                     id="footer.product.changelog"
                     description="Footer product changelog link"
@@ -107,7 +112,7 @@ function CustomFooter() {
             </h4>
             <ul className={styles.footerColumnList}>
               <li>
-                <a href="/docs/dev/" className={styles.footerColumnLink}>
+                <a href={withBaseUrl("/docs/dev/")} className={styles.footerColumnLink}>
                   <Translate
                     id="footer.resources.devDocs"
                     description="Footer resources development docs link"
@@ -117,7 +122,7 @@ function CustomFooter() {
                 </a>
               </li>
               <li>
-                <a href="/docs/dev/api/" className={styles.footerColumnLink}>
+                <a href={withBaseUrl("/docs/dev/api/")} className={styles.footerColumnLink}>
                   <Translate
                     id="footer.resources.apiReference"
                     description="Footer resources API reference link"
@@ -141,7 +146,7 @@ function CustomFooter() {
                 </a>
               </li>
               <li>
-                <a href="/docs/use/qa/" className={styles.footerColumnLink}>
+                <a href={withBaseUrl("/docs/use/qa/")} className={styles.footerColumnLink}>
                   <Translate
                     id="footer.resources.faq"
                     description="Footer resources FAQ link"
@@ -250,7 +255,7 @@ function CustomFooter() {
         </div>
         <div className={styles.footerCopyrightLinks}>
           <a
-            href="/docs/use/policy/privacy/"
+            href={withBaseUrl("/docs/use/policy/privacy/")}
             className={styles.footerCopyrightLink}
           >
             <Translate
@@ -261,7 +266,7 @@ function CustomFooter() {
             </Translate>
           </a>
           <a
-            href="/docs/use/policy/disclaimer/"
+            href={withBaseUrl("/docs/use/policy/disclaimer/")}
             className={styles.footerCopyrightLink}
           >
             <Translate
diff --git a/src/theme/Root/index.tsx b/src/theme/Root/index.tsx
index 35e12cf6..ba77de2a 100644
--- a/src/theme/Root/index.tsx
+++ b/src/theme/Root/index.tsx
@@ -1,69 +1,94 @@
 import React, { useEffect } from "react";
+import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
+import type { I18n } from "@docusaurus/types";
 
-// 全局语言检测和重定向函数
-function detectAndRedirectLanguage() {
-  // 检查是否已经执行过重定向，避免无限循环
-  if (localStorage.getItem("redirected")) {
-    return;
-  }
-
-  // 标记已执行重定向
-  localStorage.setItem("redirected", "true");
+// 浏览器语言匹配不到任何已配置 locale 时的兜底语言
+const FALLBACK_LOCALE = "en";
 
-  // 获取用户首选语言
-  const userLanguages = navigator.languages || [navigator.language];
+// 取语言标签的主子标签用于匹配：zh-Hans -> zh、ru-RU -> ru
+function primarySubtag(tag: string) {
+  return tag.split("-")[0].toLowerCase();
+}
 
-  // 检查是否包含中文语言
-  const hasChinese = userLanguages.some(
-    (lang) =>
-      lang.toLowerCase().includes("zh") || lang.toLowerCase().includes("cn")
-  );
+// 每个 locale 在 URL 上的前缀。默认 locale 挂在站点根路径上，没有前缀。
+function localePrefix(i18n: I18n, locale: string) {
+  return locale === i18n.defaultLocale ? "" : `/${i18n.localeConfigs[locale].path}`;
+}
 
-  // 只有非中文用户才需要重定向到英文版本
-  // 中文用户保持在默认中文路径
-  if (!hasChinese) {
-    // 获取当前路径（去除开头的 /）
-    // 如果当前路径是英文版本，直接使用
-    if (window.location.pathname.startsWith("/en/")) {
-      return; // 已经在英文版本，不需要重定向
+// 按 navigator.languages 的优先级顺序，挑出站点支持的 locale
+function pickLocale(i18n: I18n) {
+  const byPrimary = new Map<string, string>();
+  for (const locale of i18n.locales) {
+    const key = primarySubtag(locale);
+    // 同一主子标签下先配置的优先（如 zh-Hans 之后再加 zh-Hant 时不会被覆盖）
+    if (!byPrimary.has(key)) {
+      byPrimary.set(key, locale);
     }
-    const currentPath = window.location.pathname.replace(/^\//, "");
-    const search = window.location.search;
-    const hash = window.location.hash;
+  }
 
-    // 构建英文版本的路径
-    let englishPath = "/en/";
-    if (currentPath && currentPath !== "") {
-      englishPath += currentPath;
+  const preferred = navigator.languages?.length
+    ? navigator.languages
+    : [navigator.language];
+  for (const lang of preferred) {
+    const hit = lang && byPrimary.get(primarySubtag(lang));
+    if (hit) {
+      return hit;
     }
+  }
 
-    // 保持查询参数和锚点
-    const fullPath = englishPath + search + hash;
+  return i18n.locales.includes(FALLBACK_LOCALE)
+    ? FALLBACK_LOCALE
+    : i18n.defaultLocale;
+}
 
-    // 跳转到英文版本
-    window.location.href = fullPath;
-  } else {
-    // 中文用户重定向到默认中文路径
-    if (window.location.pathname.startsWith("/en/")) {
-      // 如果当前路径是英文版本，重定向到中文版本
-      const currentPath = window.location.pathname.replace(/^\/en\//, "/");
-      const search = window.location.search;
-      const hash = window.location.hash;
+// 拆出路径里的 locale 前缀。默认 locale 没有前缀，所以匹配不到就是默认 locale。
+// rest 始终以 / 开头，用于拼接目标 locale 的前缀。
+function splitLocale(i18n: I18n, pathname: string) {
+  for (const locale of i18n.locales) {
+    const prefix = localePrefix(i18n, locale);
+    if (prefix && (pathname === prefix || pathname.startsWith(`${prefix}/`))) {
+      return { locale, rest: pathname.slice(prefix.length) || "/" };
+    }
+  }
+  return { locale: i18n.defaultLocale, rest: pathname };
+}
 
-      // 构建中文版本的路径
-      const chinesePath = currentPath + search + hash;
+// 首次访问时按浏览器语言跳到对应语言版本，之后一直尊重用户自己选的语言。
+// 注意必须先拆掉当前路径上已有的 locale 前缀再拼新的，否则从搜索引擎直接进
+// /ru/xxx 的非中文用户会被拼成 /en/ru/xxx 这样的 404 路径。
+function detectAndRedirectLanguage(i18n: I18n) {
+  let redirected: boolean;
+  try {
+    redirected = Boolean(localStorage.getItem("redirected"));
+    localStorage.setItem("redirected", "true");
+  } catch {
+    // 隐私模式下 localStorage 不可用，记不住“已重定向”，直接跳过自动重定向，
+    // 否则每次访问都会把用户从手动选的语言上弹走
+    return;
+  }
+  if (redirected) {
+    return;
+  }
 
-      // 跳转到中文版本
-      window.location.href = chinesePath;
-    }
+  const target = pickLocale(i18n);
+  const { locale: current, rest } = splitLocale(i18n, window.location.pathname);
+  if (current === target) {
+    return;
   }
+
+  // 用 replace 而不是赋值 href，避免重定向前的地址留在历史记录里，导致点返回又被弹走
+  window.location.replace(
+    localePrefix(i18n, target) + rest + window.location.search + window.location.hash
+  );
 }
 
 export default function Root({ children }: { children: React.ReactNode }) {
+  const { i18n } = useDocusaurusContext();
+
   useEffect(() => {
     // 在客户端挂载时执行语言检测和重定向
-    detectAndRedirectLanguage();
-  }, []);
+    detectAndRedirectLanguage(i18n);
+  }, [i18n]);
 
   return <>{children}</>;
 }