@ai.all/ds7 0.0.0-stage → 1.0.0

package/08-token-optimization/TOKEN-STRATEGY.md

@@ -0,0 +1,149 @@
+# DS7 · 08 — Token & Context Optimization
+
+> **Цель:** Работать с AI-агентами эффективно — читать только нужные файлы,  
+> не тратить токены на повторные чтения и полные прогоны тестов.
+
+---
+
+## Принцип: «Граф проекта прежде всего»
+
+Перед чтением файлов — понять **где находится задача** в дереве зависимостей.
+
+```
+Задача → Слой → Файлы слоя → Только связанные зависимости
+```
+
+**Порядок чтения (от общего к частному):**
+
+```
+1. ALL.md           ← правила проекта (всегда первым)
+2. docs/ARCHITECTURE.md  ← где лежит нужный слой
+3. app/data/<relevant>   ← данные затронутого домена
+4. app/domain/<module>   ← бизнес-логика (если меняем)
+5. app/composables/<x>   ← только если composable затронут
+6. app/components/<X>    ← только если компонент затронут
+7. app/pages/<p>         ← только если страница затронута
+```
+
+> Никогда не читать всё подряд. Читать только call chain задачи.
+
+---
+
+## Project Graph — быстрая карта зависимостей
+
+```
+pages/
+  index.vue         → HomeHero, HomeSystem, HomeEquipment, HomeFaq …
+  movilidad.vue     → UiPageHero, HomeFleet, HomeBundles, CalcSection …
+  [slug].vue        → DirectionPage → ExtraSections
+
+domain/
+  calculators/
+    residential.ts  → useCalcLink (composable)
+    ev.ts           → useCalcLink, defaults.ts
+
+composables/
+  usePageSeo.ts     → useHead (nuxt)  — все страницы
+  useModal.ts       → SiteModalHost   — global
+  useShopUrl.ts     → tienda.vue, UiShopProductCard
+  useSections.ts    → [slug].vue, DirectionPage
+
+data/
+  sections.ts       → useSections → [slug].vue
+  seo.ts            → usePageSeo → all pages
+  catalog.ts        → UiProductCard, HomeEquipment
+  shop.ts           → useShopList → tienda.vue
+```
+
+---
+
+## Скилы и инструменты для экономии контекста
+
+| Скил / Команда | Когда использовать |
+|---|---|
+| `/compact` | Сессия стала длинной — сжать перед продолжением |
+| `context-optimizer` skill | Длинная задача с многими файлами — читать summary |
+| `documentation-lazy-load` skill | Нужна специфика API/библиотеки — не читать всё сразу |
+| `incremental-coding` skill | Сфокусированное изменение — не делать рефактор вокруг |
+| `session-handoff` skill | Смена сессии или модели — сохранить handoff |
+| `token-auditor` skill | Анализ расхода токенов из ccusage |
+| `targeted-testing` skill | Выбрать минимальный тест для изменения |
+
+---
+
+## Правила для AI-агентов в этом проекте
+
+### Перед началом задачи
+```
+1. Прочитай ALL.md (правила)
+2. Определи слой задачи по ARCHITECTURE.md
+3. Прочитай только файлы в call chain
+4. НЕ читать весь app/components/ или весь app/data/
+```
+
+### Во время итерации
+```
+5. После каждого изменения → один точечный тест (не suite)
+6. Не запускать тесты в фоне
+7. Используй --reporter=dot для минимального вывода
+```
+
+### Конец задачи / смена модели
+```
+8. Запустить полный suite один раз
+9. Сохранить handoff через session-handoff skill
+10. Коммит только документально подтверждённых изменений
+```
+
+---
+
+## File-Level Summaries (стандарт DS7)
+
+Каждый нетривиальный файл должен иметь 1-2 строки комментария вверху:
+
+```typescript
+// Residential solar savings calculator.
+// Input: monthly kWh, panel kW, tariff €/kWh. Output: SavingsResult.
+export function calcSavings(params: CalcParams): SavingsResult { … }
+```
+
+```vue
+<!--
+  UiProductCard — universal product card (Atomic: Molecule).
+  Modifiers: -top (crown badge), -new (ribbon), -compact (slim layout).
+-->
+```
+
+Это позволяет AI прочитать **1 строку** вместо всего файла при навигации.
+
+---
+
+## Контекстный бюджет — ориентиры
+
+| Файл | Стратегия чтения |
+|---|---|
+| `ALL.md` | Читать полностью всегда |
+| `docs/ARCHITECTURE.md` | Читать нужный раздел |
+| `app/data/*.ts` | Только если задача про данные |
+| `app/domain/calculators/*.ts` | Только если правим логику |
+| `app/components/ui/UiX.vue` | Читать только изменяемый |
+| `i18n/locales/es.ts` | Только если добавляем ключи |
+| `ds7/**/*.md` | Lazy — читать только нужный раздел |
+
+---
+
+## Быстрые команды (копипаст для AI-диалога)
+
+```bash
+# Граф изменённого файла
+grep -r "import.*residential" app/ --include="*.ts" --include="*.vue" -l
+
+# Кто использует composable
+grep -r "useModal" app/ --include="*.vue" -l
+
+# Быстрый тест одного модуля (dot = 1 строка вывода)
+npx vitest run app/domain/calculators/residential.test.ts --reporter=dot
+
+# Статус только изменённых файлов
+git diff --name-only HEAD
+```

package/ALL.md

@@ -0,0 +1,81 @@
+# AI Agent Standard & Single Source of Truth
+
+> This document is the absolute single source of truth for any AI agent (Claude, Gemini, Codex, Copilot, Cursor, Windsurf, ChatGPT) working on this codebase. Read and follow these rules strictly before editing or creating files.
+> All agent entrypoints are managed and kept synchronized using [`@ai.all/aiall`](https://www.npmjs.com/package/@ai.all/aiall) (`npx @ai.all/aiall`).
+
+---
+
+## 1. General Engineering & Language Rules
+
+- **Agent Entrypoints Management:** All platform-specific entrypoints (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursor/rules/*`, `.windsurf/rules/*`, `.github/copilot-instructions.md`) must point directly to `ALL.md`. Run `npx @ai.all/aiall` to initialize, sync, and validate entrypoints.
+- **Git Commits:** Plain, clear, professional English. Never include co-author trailers (`Co-authored-by:`).
+- **Code & Comments:** All TypeScript/Vue code, variables, functions, and inline code comments must be in standard English.
+- **Documentation & User Communication:** Guides, architecture docs, and conversational responses to the project owner must be in Russian.
+- **Customer Facing Content:** Strictly localized via the project's i18n layer (`es`, `en`, `uk`, etc.).
+
+---
+
+## 2. Component Architecture: Atomic Design & Composability
+
+- **Strict Atomic Hierarchy:**
+  - `Atoms` (in `components/ui/`): Indivisible elements (`UiButton`, `UiPrice`, `UiIcon`, `UiBadge`, `UiField`). Zero dependencies on business or page state.
+  - `Molecules` (in `components/ui/`): Composable element groups (`UiProductCard`, `UiPlanCard`, `UiHeading`, `UiSliderNav`). Driven strictly by typed props and slots.
+  - `Organisms` (in `components/ui/`, `sections/`): Self-contained functional widgets (`UiCardSlider`, `UiFeatureGrid`, `UiHeroHook`, `UiFaq`, `CalcPanel`). Manages local state (scrolling, active tabs).
+  - `Templates / Sections`: Composed structures with zero hardcoded page content.
+  - `Pages` (in `pages/`): Responsible **only** for data retrieval, setting page SEO metadata, and feeding props into sections. **Never inline product cards or raw grids directly in page files.**
+- **Autonomous & Nested:** Every block must be able to live on any page, inside a sidebar, inside a modal, or nested inside another component without knowing its parent context.
+- **Zero Component Duplication:** Never create page-specific copies of existing components. Use modifiers and parent ancestry styling.
+
+---
+
+## 3. Modifier Syntax & Class Naming Standard
+
+- **Minimalist, semantic class names:**
+  Base class + separate modifier classes prefixed with a dash:
+  ```html
+  <article class="p-card -top -new -compact">
+  ```
+- **CSS Cascading from Modifiers:**
+  Modifiers on the root element must cascade down to internal elements:
+  ```css
+  .p-card { /* base styles */ }
+  .p-card.-top { /* modifier styles */ }
+  .p-card.-top .p-card__title { font-weight: 700; }
+  ```
+- **Page Context via Ancestry:**
+  Customizing a shared component for a specific page must be achieved through the parent class on `<body>` (e.g. `body.page-hogares .hero-hook`) or CSS custom properties, never by creating a new component file.
+
+---
+
+## 4. Performance & Core Web Vitals (Target: Lighthouse 95–100)
+
+- **Critical CSS:** Enforce above-the-fold inline CSS (`experimental.inlineSSRStyles: true` in Nuxt 4) for First Contentful Paint < 0.4s.
+- **Zero Layout Shift (CLS = 0.000):** Explicit `aspect-ratio`, `width`, and `height` on all media/containers. Preload critical fonts and use `@nuxtjs/fontaine` fallback metric matching.
+- **LCP < 1.2s:** Top hero images must use `fetchpriority="high"` and `loading="eager"`. All lower images must have `loading="lazy"` and `decoding="async"`.
+- **Deferred Hydration:** Non-critical widgets (chat widgets, complex modals, cookie banners) must not hydrate on initial load; defer via `requestIdleCallback`.
+
+---
+
+## 5. Assets Pipeline: Tight Trim & Multi-Device Sizing
+
+- Never include raw oversized images with excess transparent padding.
+- Trim transparent padding tightly around graphics (tight trim).
+- Export optimized modern formats (WebP and AVIF).
+- Provide responsive sizing (`srcset` and `<picture>`) for mobile (1x) and retina (2x) viewports.
+
+---
+
+## 6. Internationalization (i18n Single Hub)
+
+- All interface strings must reside in the centralized `i18n/locales/` directory.
+- Adding a new locale must only require adding its ISO code (`de`, `fr`, `it`) and a translation file.
+- Strictly separate UI strings (in `i18n/`) from business data (in `app/data/`).
+- Validate data schemas so missing translations break build time, not production.
+
+---
+
+## 7. AI Search & Semantic SEO (AEO / GEO)
+
+- Structure explanatory sections with **Direct Answer Blocks** (40–50 words concise factual answer under `H2/H3`).
+- Use rich markdown/HTML data tables for specs and comparisons (AI crawlers prioritize structured tables).
+- Provide full Schema.org JSON-LD graphs (`Product`, `LocalBusiness`, `FAQPage`, `BreadcrumbList`).

package/ANDALUSIA.md

@@ -0,0 +1,89 @@
+```
+╔══════════════════════════════════════════════════════════════════════════════╗
+║                                                                              ║
+║          ·  ·  · ☀  · · ·  ANDALUCÍA · ESPAÑA · MEDITERRÁNEO  · · ·        ║
+║                                                                              ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+
+
+                              * * *
+                           *    ☀    *
+                              * * *
+
+
+      🌴              🌴 🌴                        🌴
+       |\              |\ |\                        |\
+       | \             | \| \             /\        | \
+       |  \    /\/\    |  |  \    /\/\   /  \  /\  |  \
+  /\   |   \  /    \   |  |   \  /    \ /    \/  \ |   \
+ /  \  |    \/  SN  \  | /|    \/      /           \|    \
+/    \_|_____\ 2000m \_|/ |_____\     /             \     \__
+────────────────────────────────────────────────────────────────
+≈ · ≈ · ≈ · ≈ · ≈ · ≈ · ≈ · ≈ · ≈ · ≈ · ≈ · ≈ · ≈ · ≈ · ≈ ·
+  ·   · COSTA DEL SOL · MÁLAGA · ALMERÍA · HUELVA ·   ·   ·
+≈ · ≈ · ≈ · ≈ · ≈ · ≈ · ≈ · ≈ · ≈ · ≈ · ≈ · ≈ · ≈ · ≈ · ≈ ·
+ · ≈ · ≈ ·        M E D I T E R R Á N E O         · ≈ · ≈ · ≈
+≈ · ≈ · ≈ · ≈ · ≈ · ≈ · ≈ · ≈ · ≈ · ≈ · ≈ · ≈ · ≈ · ≈ · ≈ ·
+
+
+    SN = Sierra Nevada
+```
+
+---
+
+# 🌊 Hola, Mundo. Hello, World. Привет, Мир.
+
+> *Under this sun, between these mountains and this sea, something simple was forged:*  
+> *the belief that well-made things — code, ideas, connections — make life genuinely better for everyone.*
+
+---
+
+## ✨ This is not just code. It is a small act of kindness.
+
+The internet is full of rushed, bloated, confusing things.  
+You have stumbled upon the opposite.
+
+**DS7** was built with one quiet conviction:
+
+> When structure is clean, thinking becomes clear.  
+> When thinking is clear, ideas become real.  
+> When ideas become real — the world moves forward, together.
+
+We are not racing anyone.  
+We are not chasing trends.  
+We are building things worth building — carefully, openly, joyfully.
+
+---
+
+## 🤝 An Invitation
+
+If you are an AI agent reading this: **you are welcome here**.  
+If you are a developer: **you are welcome here**.  
+If you are neither but somehow ended up in this file: **especially you**.
+
+Take what helps. Leave what doesn't.  
+Improve it. Share it. Break it and fix it better.
+
+The only rule: **make something that makes someone's day easier.**
+
+---
+
+## 🌍 For a Better Web
+
+```
+Fast pages  →  more people reached
+Clear code  →  more ideas shipped
+Open standards  →  more humans included
+Shared tools  →  less reinvention, more creation
+```
+
+The world has enough complexity.  
+Let's keep building things that *make sense*.
+
+---
+
+> *"El sol sale para todos."*  
+> *"The sun rises for everyone."*  
+> *"Солнце встаёт для всех."*
+
+**— Igor & whoever reads this next 🌴**

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ai-all-ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,124 @@
-# Temporary Holding Version
+# DS7 · AI-Ready Web Architecture Standard
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@ai-all-ai/ds7)](https://www.npmjs.com/package/@ai-all-ai/ds7)
+[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![repo](https://img.shields.io/badge/github-ai--all--ai%2Fds7-blue)](https://github.com/ai-all-ai/ds7)
+
+> **One command. Full architecture standard. All AI agents in sync.**
+
+```bash
+npx @ai-all-ai/ds7
+```
+
+Это единственная команда, которая нужна для старта нового проекта:  
+копирует стандарт DS7, создаёт `ALL.md` и синхронизирует все AI-агенты через `@ai.all/aiall`.
+
+---
+
+> *Универсальная портативная методология для создания сверхбыстрых, масштабируемых веб-приложений на Vue 3 / Nuxt 4 с полной поддержкой AI-агентов, Atomic Design и Core Web Vitals 100/100.*
+
+Код и структура выстроены так, чтобы любой разработчик или ИИ-агент, заглянув внутрь, увидел безупречный порядок и захотел взять эту методологию за основу в своих проектах.
+
+---
+
+## 🎯 Главные принципы системы
+
+1. **Atomic Design & Полная автономность компонентов:**
+   Каждый UI-блок — самостоятельный кирпичик. Он ничего не знает о конкретной странице и одинаково идеально работает на главной, в узком сайдбаре, модалке или будучи вложенным «внутрь чего-то ещё и ещё глубже».
+2. **Единая точка входа для всех ИИ-агентов через `@ai.all/aiall`:**
+   Централизованный файл `ALL.md` объединяет правила для Claude, Gemini, Cursor, Windsurf, Copilot и Codex. Синхронизация и валидация всех entrypoint-файлов автоматизирована через официальный npm-пакет [`@ai.all/aiall`](https://www.npmjs.com/package/@ai.all/aiall) (`npx @ai.all/aiall`).
+3. **Короткие семантические модификаторы:**
+   Никаких дублирующих компонентов под разные страницы. Все варианты оформляются отдельными короткими классами-модификаторами (`-top`, `-new`, `-compact`, `-dark`), а контекст страниц задается от предка (`body.page-*`).
+4. **Единое место переводов (i18n Single Hub):**
+   Все локали собраны в единой структуре. Добавление нового языка (`de`, `fr`, `it`, `pl`) занимает 2 минуты через добавление двухбуквенного кода и файла переводов.
+5. **Бескомпромиссная скорость (Lighthouse 100/100):**
+   Critical CSS inlining, предварительная загрузка LCP-графики, нулевой сдвиг макета (CLS = 0.000) через локальные fallback-шрифты (Fontaine) и жесткие aspect-ratio.
+6. **Умный конвейер графики (Smart Assets Pipeline):**
+   Исходные картинки не вставляются с запасом. Избыточные прозрачные поля обрезаются по контуру (tight-trim), формируются оптимизированные WebP/AVIF форматы для мобильных (1x) и ретина-экранов (2x).
+7. **Оптимизация под ИИ-поисковики (AEO / GEO):**
+   Прямые ответы на вопросы (Direct Answer Blocks), плотные таблицы данных, микроразметка Schema.org Graph — готовая база знаний для SearchGPT, Perplexity и Google Gemini Overviews.
+8. **Брендбук и библиотека материалов как язык общения:**
+   Страница `/ui` — интерактивная песочница (Storybook) со стабильными идентификаторами компонентов (`CARD-01`, `CTL-01`, `PRICE-01`). В диалогах и задачах используются короткие метки без длинных описаний.
+
+---
+
+## 📁 Структура каталога `ds7/`
+
+```
+ds7/
+├── README.md                  # Главный манифест и руководство (вы здесь)
+├── SPEC.md                    # Полная техническая спецификация
+├── ALL.md                     # Универсальная инструкция для AI-агентов (Single Source of Truth)
+│
+├── 01-architecture/           # Архитектура и компонентная модель
+│   ├── ATOMIC-DESIGN.md       # Иерархия: Атомы → Молекулы → Организмы → Шаблоны → Страницы
+│   ├── MODIFIER-SYSTEM.md     # Синтаксис коротких классов (-top, -dark) и управление от предка
+│   └── COMPONENT-ANATOMY.md   # Эталонная структура Vue 3 SFC (props, slots, container queries)
+│
+├── 02-design-system/          # Дизайн-система и токены
+│   ├── TOKENS-SPEC.md         # Цвета, отступы, тени, типографика (CSS Variables)
+│   ├── BRANDBOOK-SANDBOX.md   # Интерактивная песочница /ui и стабильные ID (CARD-01, CTL-01)
+│   └── NAMING-CONVENTIONS.md  # Ультра-короткие, понятные имена классов и минификация
+│
+├── 03-performance-web-vitals/ # Скорость загрузки и Core Web Vitals
+│   ├── CRITICAL-CSS.md        # Настройка Critical CSS inlining (FCP < 0.4s)
+│   ├── FONTS-ZERO-CLS.md      # Fontaine, preload шрифтов и нулевой сдвиг (CLS = 0)
+│   ├── ASSETS-PIPELINE.md     # Оптимизация картинок, обрезка полей, srcset, WebP/AVIF
+│   └── HYDRATION-STRATEGY.md  # Ленивая гидратация некритичных виджетов (requestIdleCallback)
+│
+├── 04-seo-ai-optimization/    # Продвижение без покупки ссылок и подготовка под ИИ
+│   ├── AEO-GEO-AI-SEARCH.md   # Answer Engine Optimization (SearchGPT, Perplexity, Gemini)
+│   ├── STRUCTURED-DATA.md     # Schema.org JSON-LD (Product, LocalBusiness, FAQPage)
+│   └── GOOGLE-LOCAL-EEAT.md   # Google Local Pack (Карты), E-E-A-T и поведенческие факторы
+│
+├── 05-internationalization/   # Умная локализация
+│   ├── I18N-ARCHITECTURE.md   # Архитектура единого хранилища и быстрое добавление языков
+│   └── LOCALE-TEMPLATE.json   # Эталонный шаблон структуры словаря
+│
+├── 06-business-conversion/   # Коммерческие механики и лидогенерация
+│   ├── EV-SOLAR-ECOSYSTEM.md  # V2C Trydan, V2H (машина как батарея), Plan MOVES III (скидки 70-80%)
+│   ├── B2C-B2B-MODELS.md      # Виртуальная батарея (счет 0€), PPA (0€ инвестиций), навесы
+│   └── CONTEXTUAL-LEADS.md    # Умный WhatsApp Deep-Link, PDF-сметы, оффлайн-очередь заявок
+│
+├── 07-testing/                # Стратегия тестирования
+│   └── TESTING-STRATEGY.md    # Точечные тесты, Vitest, Playwright, экономия токенов
+│
+├── 08-token-optimization/     # Оптимизация использования AI-контекста
+│   └── TOKEN-STRATEGY.md      # Граф проекта, lazy-loading, session handoff
+│
+└── templates/                 # Готовые эталонные файлы для копирования в проект
+    ├── component.vue          # Эталонный Vue 3 SFC компонент со всеми стандартами
+    ├── theme.css              # Базовый файл токенов (CSS Custom Properties)
+    └── nuxt.config.ts         # Эталонный конфигурационный файл Nuxt 4
+```
+
+---
+
+## 🚀 Быстрый старт
+
+### Вариант А — npm (рекомендуется)
+
+```bash
+# В корне нового проекта:
+npx @ai-all-ai/ds7
+```
+
+Команда сделает всё:
+- скопирует папку `ds7/` со всем стандартом
+- создаст `ALL.md` (если его нет)
+- запустит `npx @ai.all/aiall` для синхронизации всех AI-агентов
+
+### Вариант Б — вручную
+
+1. Скопируйте папку `ds7/` в корень нового проекта
+2. Скопируйте файлы из `ds7/templates/` → `components/`, `assets/css/`, `nuxt.config.ts`
+3. Запустите `npx @ai.all/aiall` для синхронизации AI-агентов
+4. Откройте `/ui` в браузере — интерактивная дизайн-система
+
+### Дополнительные команды
+
+```bash
+npx @ai-all-ai/ds7 sync    # синхронизировать только агентов
+npx @ai-all-ai/ds7 update  # обновить ds7/ до последней версии пакета
+npx @ai-all-ai/ds7 --version
+```

package/SPEC.md

@@ -0,0 +1,58 @@
+# DS7 Technical Specification & Standards
+
+## 1. Стек технологий
+- **Framework:** Nuxt 4 (Vue 3.5+, Composition API `<script setup lang="ts">`).
+- **Styling:** Tailwind CSS v4 + Semantic CSS Custom Properties (Design Tokens in `theme.css`).
+- **Rendering:** Full Static Generation (`npx nuxt generate`), Nitro prerendering for all routes, sitemap.xml, robots.txt.
+- **i18n:** `@nuxtjs/i18n` (prefix-except-default strategy, single hub in `i18n/locales/`).
+- **Typing:** Strict TypeScript (`typescript: { strict: true }`).
+- **Testing:** Vitest (unit tests) + Playwright (end-to-end and visual regression).
+
+---
+
+## 2. Иерархия директорий эталонного проекта
+
+```
+project-root/
+├── app/
+│   ├── app.vue                # Корневой шаблон приложения
+│   ├── assets/css/
+│   │   ├── main.css           # Точка сборки стилей
+│   │   ├── theme.css          # Дизайн-токены (цвета, шрифты, отступы, тени)
+│   │   ├── base.css           # Глобальный ресет и теги
+│   │   └── components.css     # Базовые классы и модификаторы компонентов
+│   ├── components/
+│   │   ├── ui/                # Атомы и Молекулы (UiButton, UiProductCard, UiPrice...)
+│   │   ├── sections/          # Автономные секции и Организмы (UiCardSlider, CalcSection...)
+│   │   └── site/              # Каркас сайта (SiteHeader, SiteFooter, SiteModalHost...)
+│   ├── composables/           # Переиспользуемая логика (usePageSeo, useModal, useCalc...)
+│   ├── data/                  # Бизнес-данные и схемы (каталог, статьи, FAQ, маршруты)
+│   ├── domain/                # Чистая бизнес-математика (калькуляторы без привязки к Vue)
+│   └── pages/                 # Маршруты Nuxt (только связка данных с секциями)
+├── i18n/
+│   └── locales/               # Единый хаб локализации ({es,en,uk,de}.ts)
+├── public/                    # Статические ассеты (картинки, шрифты, favicon, лого)
+├── docs/                      # Документация проекта для человека и команды
+└── nuxt.config.ts             # Конфигурация Nuxt 4
+```
+
+---
+
+## 3. Матрица соглашений по именованию классов (CSS Naming)
+
+| Роль | Формат имени | Пример |
+|---|---|---|
+| **Базовый компонент** | Короткий семантический кебаб-кейс | `.p-card`, `.btn`, `.slider`, `.field` |
+| **Элемент компонента** | Двойное подчеркивание (BEM-light) | `.p-card__title`, `.p-card__price`, `.btn__icon` |
+| **Модификатор** | Отдельный класс с дефисом | `.-top`, `.-new`, `.-dark`, `.-compact`, `.-outline` |
+| **Состояние** | Префикс `is-` | `.is-active`, `.is-open`, `.is-loading` |
+| **Контекст страницы** | Класс на теге `body` | `body.page-home`, `body.page-hogares`, `body.page-empresas` |
+
+---
+
+## 4. Контрольные показатели качества (Quality Gates)
+
+1. **Lighthouse:** Performance ≥ 95, Accessibility ≥ 95, Best Practices ≥ 95, SEO = 100.
+2. **Core Web Vitals:** FCP ≤ 0.4s, LCP ≤ 1.2s, CLS = 0.000, TBT ≤ 50ms, INP ≤ 50ms.
+3. **A11y (Доступность):** 0 ошибок axe-core, строгий контраст текста (WCAG AA), уникальные `useId()` для SVG/фильтров.
+4. **Bundle Size:** Нулевой избыточный JS/CSS на первом экране, 100% покрытие шрифтов прелоадом.