О проекте и структуре папки

Актуально на 20 июля 2026 года.

Эта папка — русскоязычная база знаний и VitePress-сайт о работе с Codex. Здесь нет исходного кода OpenAI Codex. Основной результат проекта — статическая документация, опубликованная на codex.rosveb.ru.

Проект объединяет два типа материалов:

1. Пользовательское руководство по CLI, IDE, desktop app, ChatGPT, cloud, настройке и безопасности Codex.
2. Инженерные практики: управляемый workflow, качество, тестирование, DevOps, Laravel, open source и организация контекста для coding agents.

Быстрый ответ: что находится в папке

Путь	Назначение	Редактировать вручную
README.md	Краткая точка входа для человека	Да
AGENTS.md	Правила работы coding agent в этом проекте	Только осознанно
docs/	Исходники основного VitePress-сайта	Да
docs/.vitepress/config.mts	Навигация, rewrites, поиск и настройки сборки	Да
docs/.vitepress/sync-markdown.mjs	Автоматическое включение всех project Markdown в веб	Да, с проверкой сборки
docs/project-files/	Сгенерированный каталог и копии Markdown вне docs/	Нет
docs/.vitepress/dist/	Готовый статический production-артефакт	Нет
package.json	Команды и версия VitePress корневого docs-проекта	Да
node_modules/	Установленные зависимости	Нет

В корне также находится самостоятельный вложенный проект pixel-agents/; его документация, зависимости и сборочный процесс принадлежат только этой папке, не копируются в Codex Guide и должны изменяться лишь в рамках отдельной задачи.

Что является основной документацией

Пользовательское руководство

Раздел	Содержание
docs/start/	Установка, вход, первый сеанс и выбор интерфейса
docs/cli/	Интерактивный CLI, команды, slash-команды, codex exec, config и permissions
docs/surfaces/	IDE extension и desktop app
docs/workflows/	Prompting, code review и scheduled tasks
docs/chatgpt/	Связь локального Codex с ChatGPT, cloud и handoff
docs/customization/	AGENTS.md, MCP, skills, plugins, rules и hooks
docs/safety/	Usage Policies, риск ограничений аккаунта и безопасная multi-device работа
docs/reference/	Диагностика и официальные источники
docs/final-assessment.md	Итоговые вопросы курса

Инженерные практики

Файлы docs/WORKFLOW.md, SECURITY.md, QUALITY.md и остальные документы в верхнем регистре — исходники тематических практик. VitePress публикует их через rewrites в /practices/*.html.

Начальная точка для выбора практик — docs/INDEX.md. Из-за конфликта имён с главной docs/index.md этот файл публикуется через безопасную синхронизированную копию docs/project-files/source/docs/INDEX-reference.md.

Источники истины

Используйте следующий приоритет:

1. Текущая задача пользователя и требования безопасности.
2. Ближайший AGENTS.md.
3. Фактические версии, CLI help, код и конфигурация затронутого проекта.
4. Свежий официальный Codex manual и документация OpenAI.
5. Датированные материалы этого справочника.
6. Независимые статьи и архивные ссылки.

Локальная заметка не считается доказательством текущего поведения продукта. Изменяемые сведения о Codex нужно повторно сверять с официальным источником и помечать датой проверки.

Как формируется веб-сайт

Исходные Markdown
        │
        ├─ docs/*.md и тематические каталоги
        └─ README/AGENTS и другие корневые *.md
                         │
                         ▼
              npm run docs:sync
                         │
                         ├─ общий каталог всех Markdown
                         └─ безопасные копии внешних файлов
                         │
                         ▼
              npm run docs:build
                         │
                         ▼
             docs/.vitepress/dist
                         │
                         ▼
                Caddy static site

docs:dev и docs:build автоматически выполняют docs:sync. Скрипт ищет исходные .md, исключая .git, node_modules, dist, coverage и VitePress build output. Поэтому новый Markdown обычно появляется в общем каталоге автоматически, но важную страницу всё равно нужно добавить в навигацию.

Основные команды

Установка зафиксированных зависимостей:

npm ci

Локальная разработка:

npm run docs:dev

Обновить только каталог Markdown:

npm run docs:sync

Production-сборка:

npm run docs:build

Просмотр уже собранного сайта:

npm run docs:preview

Типовые изменения

Добавить пользовательскую страницу

1. Создайте Markdown в подходящем каталоге docs/.
2. Добавьте ссылку в docs/.vitepress/config.mts, если страница должна быть видна в основном меню.
3. Добавьте официальный источник и дату проверки для изменяемых фактов.
4. Выполните npm run docs:build.
5. Проверьте новый HTML, sitemap и сохранность корневого index.html.

Обновить инженерную практику

1. Начните с docs/INDEX.md и выберите только относящийся к задаче документ.
2. Не меняйте соседние практики без необходимости.
3. Сохраните дату и происхождение рекомендаций.
4. Проверьте rewrite-маршрут /practices/... после сборки.

Опубликовать сайт

Публикация — отдельный production-шаг, а не часть npm run docs:build. Сначала проверяется локальный dist, затем артефакт синхронизируется со статическим каталогом Caddy. После публикации проверяются главная, изменённый маршрут, совпадение артефактов и внешний HTTPS-ответ.

Не изменяйте DNS, Caddy или production-сервисы только ради правки Markdown.

Критерий готовности документации

• npm run docs:build завершён успешно.
• Главная docs/.vitepress/dist/index.html существует и не пуста.
• Новые внутренние ссылки проходят проверку VitePress.
• Страница присутствует в sitemap и, если нужно, в навигации.
• Нет secrets, временных файлов, debug-вывода и случайных backup-копий.
• Указаны дата и официальный источник для изменяемых фактов.
• В отчёте разделены локальная сборка, production-публикация и внешняя проверка.

С чего начать

• Чтобы изучать Codex: откройте быстрый старт.
• Чтобы изменить сайт: прочитайте эту страницу и README.md.
• Чтобы подключить практики к другому проекту: используйте маршрутизатор практик.
• Чтобы увидеть вообще все Markdown-файлы: откройте автоматический каталог.