# AGENTS.md — рабочая инструкция для AI-агентов в flowerain-site

> Что это за проект, как устроен, что нельзя нарушать, как проверить свою
> работу. Методология разметки кода и логирования вынесена в отдельный файл
> `.agents/rules/grace-ldd.md` — здесь её нет намеренно.

## О проекте

**Flowerain** — engineering lab/studio. Этот репозиторий — официальный сайт
(`flowerain.dev`): минималистичная, атмосферная, высокопроизводительная
статическая лендинга в **одном файле**.

Бренд-философия: **«Deterministic systems meet atmospheric poetry»** —
тёмный, «промокший от дождя» терминальный вайб, точность инженерии + мистическая
атмосфера.

## Repository layout

```
flowerain-site/
├── index.html            # главная лендинга: разметка + стили + минимальный JS
├── log.html              # Transmission Log (escape-hatch к single-file, см. планы)
├── DESIGN.md             # дизайн-система (токены, типографика, компоненты)
├── README.md             # для пользователей (en)
├── AGENTS.md             # этот файл
├── scripts/              # локальные скрипты-ритуалы (черновики, не build)
└── .agents/
    ├── plans/            # планы: plan_<NN>_<semantic-id>.md (стандарт — README.md)
    └── rules/
        └── grace-ldd.md  # методология GRACE + LDD, канон — ПРИВАТНЫЙ, в .gitignore
```

## Команды

- **Сервер:** `python3 -m http.server 8000` или `npx serve .`
- **Билд:** отсутствует — статика, ноль зависимостей.
- **Деплой:** Cloudflare Pages (ещё не подключен) — статический экспорт корня.

## Стек и ограничения

- Единственный файл `index.html`: HTML + CSS + минимальный vanilla JS.
- Никаких фреймворков, билд-цепочек, пакетных менеджеров, node_modules.
- **Только контролируемые свои эндпоинты при загрузке** — same-origin файлы
  (напр. `/log.json`); никаких сторонних CDN/сервисов. Шрифты только системные/локальные.
- Токены дизайна (палитра, типографика) — только в `:root` как `var(--*)`;
  хардкод hex в селекторах запрещён.

Любое нарушение перечисленного — только с явного согласия владельца.

## Бренд и дизайн-контекст

- **Якорь:** 💮 (White Flower / Hanamaru) — символ заботы, личности агента,
  верифицированного ground-truth.
- **Палитра:** глубокий slate `#0b0d10`, графит `#12161c`, тонкие рамки
  `#1f2630`; акценты — petal white `#f4f4f6`, сакура/кармин `#ff6b8b` / `#e05670`.
- **Шрифты:** моноширинные для кода/данных (JetBrains Mono), чистые для текста
  (Inter) — системные fallback, без CDN.
- **Интерактив:** лёгкий (hover-эффекты, canvas-дождь / CSS-свечение,
  ambient-шум/blur). Всегда с уважением к `prefers-reduced-motion`.

### Секции лендинга

1. **Hero:** 💮, «FLOWERAIN», однострочный манифест, статус-бейдж
   («Developing Khan Engine on Zig 0.16.0»).
2. **The World OS (Khan Engine):** карточки с 4-частной формулой
   *Intent / Truth / Control / Trust* и тех-хайлайты (ECS, MCP, Determinism).
3. **Agents & Simulation:** глимпс agent citizenship и верифицируемых миров.
4. **Transmissions:** топ-3 записей из `/log.json`; полный лог — отдельная
   страница `/log.html` (контентное исключение из single-file).
5. **Footer:** GitHub `github.com/flowerain-labs`, architect `khanecho`, копирайт.

## Что строим (миссия)

- **Khan Engine** — AI-native World OS на Zig 0.16.0 + ECS. Детерминированная
  симуляция, MCP, семантические интерфейсы. Формула: «LLM gives intent. Engine
  gives truth. Editor gives human control. Evidence gives trust.»
- **Itrains** — интерактивная мистическая тёмная реальность / симулированный мир.
- **Ценности:** Determinism · Observable Evidence · Agent Citizenship ·
  Semantic Interfaces.

## Планы

- Все планы — в `.agents/plans/` по стандарту `.agents/plans/README.md`:
  `plan_<NN>_<semantic-id>.md` (порядок по номеру, суть — по семантическому имени).
- Новая идея = следующий файл плана. План — якорь сессий: реализуй по шагам,
  статус обновляй в мета-блоке (`draft|active|done|deferred`).
- Актуальный план на текущий момент — читай первым.

## Как работать

1. Перед правкой — прочитай `README.md`, `DESIGN.md` (дизайн-токены и компоненты),
   этот файл, актуальный план из `.agents/plans/` и `.agents/rules/grace-ldd.md`
   (разметка кода и формат логов — там; приватный, но на этой машине доступен).
2. Правки основного сайта — внутри `index.html`; контентные страницы-исключения —
   по плану (см. `log.html`).
3. `log.json` — не правится руками: перегенерируется
   `scripts/gen-transmissions.sh` (git приватного khan-engine → черновик → append).
   Менять можно паттерны в `scripts/transmissions.json`.
4. Палитра/шрифты — через `var(--*)` из `:root`, не магическими значениями.
   Токены в `:root` соответствуют DESIGN.md 1:1.
5. Логи в консоль — по канону из grace-ldd.md; не спамить в rAF-циклах.

## Проверка перед сдачей

1. Открыть в браузере: консоль без ошибок и предупреждений.
2. Вьюпорты 320 / 768 / 1440 px — без полос, скролла вбок и обрезанного текста.
3. `prefers-reduced-motion` — анимации/свечение отключаются или замедляются.
4. Контраст текста на фоне — доступный (WCAG AA минимум).
5. Ноль layout shift: размеры контента не прыгают при загрузке/ресайзе.
6. Нет сторонних запросов: Network tab без CDN/третьих сервисов; только
   same-origin (index.html, font, log.json).

## Ссылки

- Сайт: `flowerain.dev`
- GitHub: `github.com/flowerain-labs`
- Architect: `khanecho`