@ai.all/ds7 1.0.0 → 2.0.0

package/06-business-conversion/EV-SOLAR-ECOSYSTEM.md

@@ -1,38 +1,38 @@
-# 06-Business · EV & Solar Ecosystem (V2C, V2H, Plan MOVES III)
+# 06 · Electric vehicles and solar (example)
 
-> Современная связка солнечной энергетики и электромобильности. Как продавать умные зарядные станции и станции самопотребления.
+> Example from a Spanish solar company. Product names, subsidy programmes and amounts are examples. Verify them before use.
 
 ---
 
-## 1. Зарядка от излишков солнца (100% Solar Surplus)
+## 1. Charging from surplus solar
 
-Станции испанского производителя **V2C Trydan** — якорный продукт для направления `Movilidad`:
-* **Принцип:** Станция связывается по Wi-Fi с инвертором (Huawei, Livoltek, GoodWe). Если дом потребляет 1 кВт, а панели генерируют 5 кВт, оставшиеся 4 кВт излишка автоматически направляются в батарею автомобиля.
-* **Выгода:** Машина заряжается **чистой бесплатной энергией солнца (0 € расходов)**, не покупая ни одного кВт·ч из сети.
+A home charger connected to the inverter over the local network can direct surplus solar power to the car. A household that uses 1 kW while the panels make 5 kW sends the remaining 4 kW to the car.
+
+**Benefit for the customer:** the car charges from solar energy that would otherwise go to the grid.
+
+Check the compatible inverter brands before you promise this.
 
 ---
 
-## 2. Метрика «Солнечный километр»
+## 2. Show the benefit in terms people use
+
+Technical units (kW, amperes, volts) are hard to compare. Show the result in distance or money:
 
-Клиентам тяжело воспринимать абстрактные технические показатели (кВт, амперы, вольты).
-В интерфейсе все формулы переводятся в **километры бесплатной езды**:
-* *«6 солнечных панелей на крыше = 45 км бесплатного ежедневного пробега»*.
-* *«Экономия на заправке автомобиля: более 180 € в месяц по сравнению с бензином»*.
+- "Six panels on the roof give about 45 km of driving per day."
+- "Compared with petrol, the monthly saving can exceed [amount calculated for this customer]."
+
+State the assumptions next to the figure.
 
 ---
 
-## 3. V2H (Vehicle-to-Home) — Электромобиль как аккумулятор дома
+## 3. Vehicle-to-home (V2H)
+
+A typical home battery stores about 5 kWh. A modern electric vehicle battery stores several times more. With V2H, the car supplies the home in the evening peak or during a grid outage, if the charger and the car support it.
 
-* Обычная домашняя батарея (например, 5 кВт·ч) стоит около 3 000 €.
-* Батарея современного электромобиля — **60–80 кВт·ч** (в 12–15 раз больше!).
-* Технология V2H позволяет использовать емкость электромобиля для питания дома в вечерние часы пиковых тарифов или при аварийных отключениях электросети.
+Say which models support V2H. Do not offer it to a customer whose hardware does not.
 
 ---
 
-## 4. Субсидии Plan MOVES III (Возврат до 70–80%)
+## 4. Subsidies
 
-Государственная программа Испании компенсирует большую часть стоимости зарядной станции и ее монтажа:
-* В карточках товаров V2C всегда выводятся две цены:
-  * Базовая цена оборудования;
-  * **Финальная цена после субсидии Plan MOVES III** (`782 € → 234 €`).
-* Это снимает ценовые возражения и стимулирует покупку комплекта «Панели + Зарядка».
+Public programmes can cover part of the charger and installation cost. In the example company's catalogue, each product shows two prices: the equipment price and the price after the programme's share. Show both, with the programme name and the source.

package/07-testing/TESTING-STRATEGY.md

@@ -1,133 +1,95 @@
-# DS7 · 07 — Targeted Testing Strategy
+# 07 · Testing strategy
 
-> **Принцип:** Запускай минимально достаточный тест — не весь suite.  
-> Полный прогон — только перед PR/деплоем. Ежедневная разработка — точечные проверки.
+Run the smallest test that proves the change. Run the full suite once before a commit that finishes a task.
 
 ---
 
-## Иерархия тестов (от быстрого к медленному)
+## 1. Layers, fastest first
 
 ```
-1. Unit (domain logic)      ~10ms/test    → запускать всегда при изменении логики
-2. Composable (Vue reactive) ~50ms/test   → при изменении composable
-3. Component (Vue TU)        ~200ms/test  → при изменении компонента
-4. E2E / Playwright          ~5s/flow     → только критичные пути, перед релизом
+1. Unit (domain logic)         ~10 ms per test    run when logic changes
+2. Composable (Vue reactivity) ~50 ms per test    run when a composable changes
+3. Component (Vue Test Utils)  ~200 ms per test   run when a component changes
+4. End-to-end (Playwright)     ~5 s per flow      key paths, before release
 ```
 
+Accessibility checks (axe) run on every page at 390, 820 and 1440 px as part of the quality gates.
+
 ---
 
-## Инструменты
+## 2. Tools
 
-| Инструмент | Назначение |
+| Tool | Use |
 |---|---|
-| **Vitest** | Unit + composable + component тесты |
-| **@vue/test-utils** | Маунт Vue-компонентов без браузера |
-| **Playwright** | E2E (checkout, calculator flow, 404) |
+| Vitest | unit, composable and component tests |
+| `@vue/test-utils` | mounting components without a browser |
+| Playwright | flows (calculator, contact, 404) and screenshots for review |
+| axe-core | accessibility rules, through Playwright |
 
 ---
 
-## Команды — точечные запуски
+## 3. Commands
 
 ```bash
-# Один файл
-npx vitest run app/domain/calculators/residential.test.ts
-
-# Одна папка
-npx vitest run app/domain/calculators/
-
-# По имени теста
-npx vitest run -t "savings calculator"
-
-# Минимальный вывод (экономит токены в AI-диалоге)
-npx vitest run --reporter=dot
-
-# Полный suite — только перед коммитом
-npx vitest run
-
-# Watch (только при локальной разработке)
-npx vitest --reporter=dot
+npx vitest run path/to/file.test.ts          # one file
+npx vitest run path/to/folder/               # one folder
+npx vitest run -t "savings"                  # by test name
+npx vitest run --reporter=dot                # short output
+npx vitest run                               # full suite, before a finishing commit
 ```
 
 ---
 
-## Правила именования тестов
+## 4. Naming
 
-```typescript
-// ✅ Описательное: что тестируем + ожидаемый результат
-it('calculates savings with 30% self-consumption correctly', () => { ... })
+```ts
+// good: what is tested and what is expected
+it('calculates savings with 30% self-consumption', () => { … })
 
-// ❌ Слабое: непонятно что ломается
-it('works', () => { ... })
+// poor: says nothing about what breaks
+it('works', () => { … })
 ```
 
 ---
 
-## Структура тест-файла
-
-```typescript
-// app/domain/calculators/residential.test.ts
+## 5. Test file shape
 
+```ts
 import { describe, it, expect } from 'vitest'
 import { calcSavings } from './residential'
 
-// Self-contained: тест запускается изолированно без глобального setup
 describe('calcSavings', () => {
   it('returns zero savings for zero consumption', () => {
     expect(calcSavings({ kwhMonth: 0, panelKw: 5, tariff: 0.18 })).toBe(0)
   })
 
-  it('caps savings at 100% of bill', () => {
+  it('caps savings at the full bill', () => {
     const r = calcSavings({ kwhMonth: 100, panelKw: 20, tariff: 0.18 })
     expect(r.savingsPct).toBeLessThanOrEqual(100)
   })
 })
 ```
 
----
-
-## Правила тестового покрытия
-
-| Слой | Покрытие | Инструмент |
-|---|---|---|
-| `domain/calculators/` | **≥ 90%** | Vitest unit |
-| `composables/` | **≥ 70%** | Vitest + @vue/test-utils |
-| `components/ui/` | **критичные пути** | @vue/test-utils |
-| `pages/` | **smoke только** | Playwright |
-
-> **Не тестировать:** статичные данные (`app/data/`), CSS, переводы (i18n) — их не нужно юнит-тестировать.
+Each test file runs alone, without a global setup that the test depends on.
 
 ---
 
-## Стратегия для AI-агентов (экономия токенов)
+## 6. Coverage expectations
 
-1. **Перед правкой** — запусти только тест изменяемого файла
-2. **После правки** — снова только этот тест (`--reporter=dot`)
-3. **Расширяй scope** только если изменение затронуло shared logic
-4. **Полный suite** — один раз в конце задачи, не в каждой итерации
+| Layer | Expectation |
+|---|---|
+| `domain/` | high; every branch of business rules |
+| `composables/` | main paths and error paths |
+| `components/ui/` | critical interactions only |
+| `pages/` | smoke test: renders, has one `h1`, no console errors |
 
-```bash
-# Шаблон для AI-итерации (минимум токенов):
-npx vitest run path/to/changed.test.ts --reporter=dot
-```
+Do not unit-test static data, copy or CSS. Copy is checked by the locale parity gate; CSS by the visual review in the sandbox.
 
 ---
 
-## Vitest Config (рекомендуемый минимум)
-
-```typescript
-// vitest.config.ts
-import { defineConfig } from 'vitest/config'
-
-export default defineConfig({
-  test: {
-    environment: 'jsdom',
-    include: ['**/*.test.ts'],
-    exclude: ['node_modules', 'ds7', 'dist'],
-    reporter: process.env.CI ? 'verbose' : 'dot',  // dot = меньше вывода
-    coverage: {
-      include: ['app/domain/**', 'app/composables/**'],
-      reporter: ['text-summary'],  // краткий отчёт, не таблицы
-    },
-  },
-})
-```
+## 7. Token-efficient testing for agents
+
+1. Before editing, know which test covers the file.
+2. After editing, run that test with `--reporter=dot`.
+3. Widen the scope only if shared logic changed.
+4. Run the full suite once at the end of the task.

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

@@ -1,149 +1,100 @@
-# DS7 · 08 — Token & Context Optimization
+# 08 · Token and context optimisation
 
-> **Цель:** Работать с AI-агентами эффективно — читать только нужные файлы,  
-> не тратить токены на повторные чтения и полные прогоны тестов.
+Goal: an agent reads what the task needs and nothing else, and does not repeat work.
 
 ---
 
-## Принцип: «Граф проекта прежде всего»
+## 1. Map before reading
 
-Перед чтением файлов — понять **где находится задача** в дереве зависимостей.
+Find the layer of the task first, then read only the files on its call chain:
 
 ```
-Задача → Слой → Файлы слоя → Только связанные зависимости
+task → layer → files of the layer → direct dependencies only
 ```
 
-**Порядок чтения (от общего к частному):**
+Reading order, from general to specific:
 
-```
-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>         ← только если страница затронута
-```
+1. `ds7/ALL.md` (standard rules), then the project section of the root `ALL.md`, below the AI-ALL packs block (project rules and decisions).
+3. `docs/ARCHITECTURE.md` (layer map).
+4. `app/data/<relevant>` if the task concerns data.
+5. `app/domain/<module>` if the task changes business logic.
+6. `app/composables/<name>` if a composable is involved.
+7. `app/components/<name>` if a component is changed.
+8. `app/pages/<name>` if a page is changed.
 
-> Никогда не читать всё подряд. Читать только call chain задачи.
+Do not read all of `app/components/` or all of `app/data/`.
 
 ---
 
-## Project Graph — быстрая карта зависимостей
+## 2. Project graph
+
+Keep a short graph in `docs/ARCHITECTURE.md`, one line per dependency, so the agent can find callers without searching:
 
 ```
-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
+pages/index.vue       → Hero, Systems, Equipment, Faq
+composables/usePageSeo → useHead, all pages
+data/catalog.ts       → ProductCard, Equipment
 ```
 
----
-
-## Скилы и инструменты для экономии контекста
-
-| Скил / Команда | Когда использовать |
-|---|---|
-| `/compact` | Сессия стала длинной — сжать перед продолжением |
-| `context-optimizer` skill | Длинная задача с многими файлами — читать summary |
-| `documentation-lazy-load` skill | Нужна специфика API/библиотеки — не читать всё сразу |
-| `incremental-coding` skill | Сфокусированное изменение — не делать рефактор вокруг |
-| `session-handoff` skill | Смена сессии или модели — сохранить handoff |
-| `token-auditor` skill | Анализ расхода токенов из ccusage |
-| `targeted-testing` skill | Выбрать минимальный тест для изменения |
+Update it when a dependency changes.
 
 ---
 
-## Правила для AI-агентов в этом проекте
+## 3. Working rules
 
-### Перед началом задачи
-```
-1. Прочитай ALL.md (правила)
-2. Определи слой задачи по ARCHITECTURE.md
-3. Прочитай только файлы в call chain
-4. НЕ читать весь app/components/ или весь app/data/
-```
+**Before the task**
+1. Read `ds7/ALL.md` and the project section of the root `ALL.md`.
+2. Find the layer in `docs/ARCHITECTURE.md`.
+3. Read only the files on the call chain.
 
-### Во время итерации
-```
-5. После каждого изменения → один точечный тест (не suite)
-6. Не запускать тесты в фоне
-7. Используй --reporter=dot для минимального вывода
-```
+**During the task**
+4. After each change, run one targeted test.
+5. Do not start background processes unless needed.
+6. Use `--reporter=dot` for short test output.
 
-### Конец задачи / смена модели
-```
-8. Запустить полный suite один раз
-9. Сохранить handoff через session-handoff skill
-10. Коммит только документально подтверждённых изменений
-```
+**At the end**
+7. Run the full suite once.
+8. Record decisions in `docs/DECISIONS.md`, not in the chat.
+9. Commit only what is verified.
 
 ---
 
-## File-Level Summaries (стандарт DS7)
+## 4. File summaries
 
-Каждый нетривиальный файл должен иметь 1-2 строки комментария вверху:
+Each non-trivial file starts with one or two lines describing it. An agent can read the first line to decide whether to open the file:
 
-```typescript
-// Residential solar savings calculator.
-// Input: monthly kWh, panel kW, tariff €/kWh. Output: SavingsResult.
-export function calcSavings(params: CalcParams): SavingsResult { … }
+```ts
+// Residential savings calculator. Input: monthly kWh, panel kW, tariff €/kWh. Output: SavingsResult.
 ```
 
 ```vue
 <!--
-  UiProductCard — universal product card (Atomic: Molecule).
-  Modifiers: -top (crown badge), -new (ribbon), -compact (slim layout).
+  UiProductCard — product card molecule.
+  Modifiers: -top (highlight), -new (ribbon), -compact (slim).
 -->
 ```
 
-Это позволяет AI прочитать **1 строку** вместо всего файла при навигации.
-
 ---
 
-## Контекстный бюджет — ориентиры
+## 5. Budget guide
 
-| Файл | Стратегия чтения |
+| File | Reading strategy |
 |---|---|
-| `ALL.md` | Читать полностью всегда |
-| `docs/ARCHITECTURE.md` | Читать нужный раздел |
-| `app/data/*.ts` | Только если задача про данные |
-| `app/domain/calculators/*.ts` | Только если правим логику |
-| `app/components/ui/UiX.vue` | Читать только изменяемый |
-| `i18n/locales/es.ts` | Только если добавляем ключи |
-| `ds7/**/*.md` | Lazy — читать только нужный раздел |
+| `ds7/ALL.md` | whole file, always |
+| Project section of root `ALL.md` | whole section, always |
+| `docs/ARCHITECTURE.md` | the section that matches the layer |
+| `app/data/*.ts` | only when the task concerns data |
+| `app/domain/*.ts` | only when business logic changes |
+| `app/components/ui/*.vue` | only the file being changed |
+| `i18n/locales/*.ts` | only when keys are added |
+| `ds7/**/*.md` | on demand, one section |
 
 ---
 
-## Быстрые команды (копипаст для AI-диалога)
+## 6. Useful commands
 
 ```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
+grep -rl "useModal" app/ --include="*.vue"          # who uses a composable
+npx vitest run path/to/file.test.ts --reporter=dot   # one test, minimal output
+git diff --name-only HEAD                            # what changed
 ```