Документация (агентам)

Кратко. Детали для людей: docs/CONTENT-GUIDE.md. Карта: docs/CODEMAP.md. На сайтах: Портал /howto-skills, SmartDCIM /howto-skills.

Куда писать

Сайт	Порт	Файлы	URL
Портал ЦП — портал	4173	site/docs/portal/	/… (без префикса)
Портал ЦП — ЦП	4173	site/docs/cpult/	/cpult/…
SmartDCIM	4174	site_dcim/docs/	/…

• Sync: cd site && npm run sync затирает site/docs/{portal,cpult} из content/ / content/cpult/. Правь источник sync или только site/docs/… если sync не гоняете.
• Меню = дерево .md + папки. Не править sidebar вручную в config.mts.
• Имена файлов/папок: латиница, a-z0-9-_, без кириллицы и пробелов. Русский — в # и _labels.json.

Новый раздел / статья

Одиночная страница: …/topic.md + # Заголовок (один H1).

Раздел с детьми:

section/
  index.md      # обложка (необязательно)
  page.md
  nested/…

Короткое имя в меню: _labels.json рядом с корнем дерева (portal/, cpult/, или корень SmartDCIM).

{ "getting-started.md": "Начало работы", "glossary": "Глоссарий" }

Ключи: file.md | dir | path/dir | path/file.md.

Ссылки

• ЦП: […](/cpult/path) или /cpult/path/
• Портал: […](/home), […](/asds/…)
• SmartDCIM: […](/path) без /cpult
• Картинки: /assets/… или /assets/cpult/…

Формат MD (обязательно)

• Один # на файл.
• ## / ### для структуры.
• Таблицы, списки, ``` — обычный GFM.
• Голые <теги> вне кода ломают Vue (<number>, <id>, <host>). Пиши <number> или `<number>`.
• Не выкидывай чужой HTML из зеркала Antora без нужды.
• Панель MD → Vue (dev): крошки пути + строка + что экранировать. Эндпоинт /__md-issues.

Чего не делать

• Кириллица в путях на диске.
• Класть ЦП в portal/ и наоборот.
• Коммитить users.json / .env с секретами.
• Дублировать длинные гайды в чат — следуй этому skill; люди читают CONTENT-GUIDE.

Проверка

1. Файл .md на месте, латиница в имени.
2. Dev: site → :4173, site_dcim → :4174.
3. Пункт в сайдбаре + открытие URL + внутренние ссылки.
4. Нет красной панели MD → Vue на странице (или пофикси голые теги).

Деплой / архивы (агентам и админам)

Действие	Команда
Собрать портал (≥4 GiB RAM)	cd site && NODE_OPTIONS=--max-old-space-size=4096 npm run build (+ fill-lean)
Упаковать портал (+dist)	./scripts/pack-site.sh → dist/saymon-portal-site-YYYYMMDD.tar.gz
Собрать SmartDCIM	cd site_dcim && NODE_OPTIONS=--max-old-space-size=4096 npm run build
Упаковать SmartDCIM (+dist)	./scripts/pack-dcim.sh → dist/smartdcim-docs-site-YYYYMMDD.tar.gz
Слабый хост (≤2 GiB)	архив с docs/.vitepress/dist + ./install.sh --prebuilt
Портал prod	serve.mjs + systemd (ставит install.sh); nginx proxy_pass → :4173
SmartDCIM prod	vitepress preview / install-dcim; nginx → :4174

Ключи install.sh (Портал): INSTALL_DIR, AUTH_SECRET, PORTAL_USER/PORTAL_PASSWORD, PORTAL_HOST/PORTAL_PORT, INSTALL_NODE=1, NODE_HEAP_MB, FORCE_BUILD=1, SKIP_SYSTEMD=1, --prebuilt / --build-only / --dev.

SmartDCIM: install-dcim.sh → DCIM_HOST/DCIM_PORT, те же --prebuilt / Node.

Не ломать hydrate (Портал + DCIM):

• Build всегда с scripts/fill-lean.mjs (пустые *.lean.js → пустая страница после JS).
• Не включать в prod SidebarActiveScroll (клики/DOM по сайдбару → шапка, пустой #VPContent, особенно /cpult/).
• MdErrorPanel только import.meta.env.DEV.
• Портал: не vitepress preview — только node serve.mjs (иначе auth 404).

Auth портала = cookie + serve.mjs за reverse proxy. Голый nginx по dist/ = без логина.

Детали: корневой README.md.