docs: рефакторинг документации — workflow, прикладные разделы, генерация RULES.md

- Переработан раздел Workflow: заголовки, описания, порядок разделов
- Добавлены новые разделы: Генерация кода (workflow), Настройка VS Code (applied)
- Убран суффикс .ui.tsx из документации и примеров
- Переработан раздел Структура проекта — только Next.js, без React SPA
- Приоритет стилизации перенесён из applied/styles в workflow/styling
- Убрано дублирование инструментов генерации — единая точка в applied/templates-generation
- Переписан concat-md.js: без внешних зависимостей, мета-якоря для навигации в RULES.md
- Удалена зависимость concat-md
- Обновлена главная страница: названия разделов, URL на RULES.md
- Добавлен AGENTS.md с правилами для агентов

concat-md.js

@@ -1,4 +1,3 @@
-import { concatMdSync } from "concat-md";
 import path from "path";
 import fs from "fs";
 
@@ -9,6 +8,7 @@ const fileOrder = [
   // workflow
   "workflow/getting-started.md",
   "workflow/creating-app.md",
+  "workflow/code-generation.md",
   "workflow/creating-pages.md",
   "workflow/creating-components.md",
   "workflow/styling.md",
@@ -23,8 +23,10 @@ const fileOrder = [
   "basics/documentation.md",
   "basics/typing.md",
   // applied
+  "applied/vscode.md",
   "applied/project-structure.md",
   "applied/components.md",
+  "applied/page-level.md",
   "applied/templates-generation.md",
   "applied/styles.md",
   "applied/images-sprites.md",
@@ -37,6 +39,27 @@ const fileOrder = [
   "applied/localization.md",
 ];
 
+// Удалить frontmatter из содержимого md-файла
+const stripFrontmatter = (content) =>
+  content.replace(/^---[\s\S]*?---\n*/m, "");
+
+// Сдвинуть уровень заголовков на 1 вниз (h1→h2, h2→h3, ...)
+// Не трогает заголовки внутри блоков кода
+const shiftHeadings = (content) => {
+  const lines = content.split("\n");
+  let inCodeBlock = false;
+
+  return lines
+    .map((line) => {
+      if (line.startsWith("```")) inCodeBlock = !inCodeBlock;
+      if (inCodeBlock) return line;
+      if (/^#{1,5}\s/.test(line)) return "#" + line;
+      return line;
+    })
+    .join("\n");
+};
+
+// Собрать RULES.md с мета-якорями для каждого файла
 const buildRules = (lang) => {
   const srcDir = `./docs/${lang}`;
   const outDir = `./generated/${lang}`;
@@ -49,18 +72,24 @@ const buildRules = (lang) => {
 
   fs.mkdirSync(outDir, { recursive: true });
 
-  const resultMd = concatMdSync(srcDir, {
-    toc: false,
-    sorter: (a, b) => {
-      const indexA = fileOrder.indexOf(a);
-      const indexB = fileOrder.indexOf(b);
-      const posA = indexA === -1 ? fileOrder.length : indexA;
-      const posB = indexB === -1 ? fileOrder.length : indexB;
-      return posA - posB;
-    },
-  });
+  const parts = [];
 
-  fs.writeFileSync(outFile, resultMd, "utf8");
+  for (const file of fileOrder) {
+    const filePath = path.join(srcDir, file);
+    if (!fs.existsSync(filePath)) continue;
+
+    const raw = fs.readFileSync(filePath, "utf8");
+    const content = stripFrontmatter(raw).trim();
+    if (!content) continue;
+
+    // Мета-якорь: путь VitePress без расширения
+    const route = "/" + file.replace(/\.md$/, "");
+    // index.md остаётся без сдвига (его h1 — главный заголовок документа)
+    const processed = file === "index.md" ? content : shiftHeadings(content);
+    parts.push(`<!-- ${route} -->\n${processed}`);
+  }
+
+  fs.writeFileSync(outFile, parts.join("\n\n"), "utf8");
   console.log(`RULES.md (${lang}) создан: ${outFile}`);
 };
 
@@ -77,9 +106,7 @@ const buildReadme = (lang, outFile) => {
     return;
   }
 
-  const content = fs.readFileSync(indexPath, "utf8")
-    .replace(/^---[\s\S]*?---\n*/m, "");
-
+  const content = stripFrontmatter(fs.readFileSync(indexPath, "utf8"));
   fs.writeFileSync(outFile, content, "utf8");
   console.log(`${outFile} создан из ${indexPath}`);
 };