@ai.all/ds7 1.0.0 → 2.0.0

package/ALL.md

@@ -1,81 +1,232 @@
-# AI Agent Standard & Single Source of Truth
+# ALL.md — Agent Rules for DS7 Projects
 
-> 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`).
+> **How it fits with AI-ALL.** [AI-ALL](https://github.com/ai-all-ai/aiall) (`@ai.all/aiall`) creates the agent entrypoints and the routing file, and keeps them in sync. This document is delivered to agents as the `ds7` pack of AI-ALL. AI-ALL works without DS7; for web projects, install both.
+
+
+> Single source of truth for every AI agent working in a DS7 project (Claude, Gemini, Codex, Copilot, Cursor, Windsurf, ChatGPT).
+> Read this file completely before changing anything. Other files in `ds7/` explain *why* a rule exists; this file says *what to do*.
+> Project-specific rules live in the root `ALL.md`, below the AI-ALL packs block (`<!-- aiall:begin packs -->` to `<!-- aiall:end packs -->`). AI-ALL keeps that text on sync. Where project rules and this file disagree, the project rules win for that project and the disagreement is recorded in `docs/DECISIONS.md`.
+> This file is the `ds7` pack of AI-ALL. The root `ALL.md` lists it in the packs block. Every entrypoint (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursor/rules/*`, `.windsurf/rules/*`, `.github/copilot-instructions.md`) points to the root `ALL.md`. Sync them with `npx @ai.all/aiall sync`.
+
+**Version:** 1.1.0 · **Stack:** Nuxt 4, Vue 3 `<script setup lang="ts">`, Tailwind CSS v4, `@nuxtjs/i18n`, static generation.
+
+---
+
+## 0. Ground rules (apply to everything below)
+
+1. **Read before writing.** Read the file you change and its direct callers. Do not read whole folders.
+2. **Smallest correct change.** Fix the cause in one place. Do not refactor around a bug you were not asked to fix.
+3. **Describe reality.** Docs, comments, tests and UI copy state what the code does today. No marketing claims, no unmeasured numbers presented as facts.
+4. **No junk in the repo.** No scratch files, debug logs, screenshots, backups or generated reports in tracked folders. Temporary work goes to a scratch directory outside the repo.
+5. **Ask only when it changes the outcome.** Otherwise pick the most reasonable option, do it, and say what you chose.
+
+---
+
+## 0.1 Build order: brand first, then components
+
+New projects and new sections are built **top-down from the brand**, never by styling pages one by one:
+
+1. **Foundations** (`theme.css`): colour, type scale, spacing, radius, shadow, breakpoints, z-index. Written as named tokens, with the W3C Design Tokens format (`$value`, `$type`) as the interchange shape if tools need it.
+2. **Brandbook** (`/ui` sandbox): every foundation token shown, then the base atoms (`BTN-01`, `BTN-02`, `CTL-01`, `COUNTER-01`, `PRICE-01`) with their modifiers, states and contrast on light and dark backgrounds.
+3. **Atoms and molecules** built from the brandbook only. A component that is not in the sandbox is not finished.
+4. **Organisms and sections** composed from molecules.
+5. **Pages** assembled from sections, with data from `app/data/`.
+
+Rules that follow from this order:
+
+- A new colour, size or spacing value is added to the foundations first. Components never introduce a raw value.
+- A new pattern is added to the brandbook first, then used. If a page needs something that does not exist, add it to the brandbook, then use it.
+- Changing a token changes the brandbook, which is the visual regression reference.
+- The brandbook is the shared vocabulary: people and agents refer to `CARD-01 -top` instead of describing it again.
+
+This approach is established practice, not an invention of DS7. Related references: the [W3C Design Tokens Format Module (2025.10)](https://www.w3.org/community/reports/design-tokens/CG-FINAL-format-20251028/) defines the token file format; [Brad Frost's Atomic Design](https://atomicdesign.bradfrost.com/chapter-2/) defines the component levels; design systems such as Salesforce Lightning and Material Design publish foundations and component guidance before components are used in product pages. Token pipelines such as Style Dictionary turn one token file into CSS, iOS and Android values.
 
 ---
 
-## 1. General Engineering & Language Rules
+## 1. Languages
 
-- **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.).
+- **Code, comments, identifiers, commit messages, docs in `ds7/` and `docs/`:** English.
+- **Conversation with the project owner:** the owner's language (unless the owner says otherwise).
+- **Customer-facing text:** only through the i18n layer (`i18n/locales/`). Never hard-code a user-visible string in a component or page.
+- **Business data** (`app/data/`) is separate from UI strings (`i18n/`). Missing translations must fail the build.
 
 ---
 
-## 2. Component Architecture: Atomic Design & Composability
+## 2. Components (Atomic Design)
 
-- **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.
+Full model: `01-architecture/ATOMIC-DESIGN.md`.
+
+| Level | Location | Rule |
+|---|---|---|
+| Atoms | `components/ui/` | No knowledge of pages or business state. Typed props only. |
+| Molecules | `components/ui/` | Built from atoms. Props and slots only. No side effects. |
+| Organisms | `components/ui/`, `components/sections/`, `components/site/` | Own their local state. Work through slots. |
+| Sections / templates | `components/sections/` | Compose organisms. No hard-coded page content. |
+| Pages | `pages/` | Only: fetch data from `app/data/`, set SEO, pass props. **No inline cards, grids or sliders.** |
+
+- **Never copy a component for a page.** Vary it with modifiers or with the page class on `<body>`.
+- **Every block works anywhere** (page, sidebar, modal, nested). It must not depend on its parent.
+- **Every reusable pattern has a stable ID** (`CARD-01`, `BTN-01`, …) listed in `02-design-system/BRANDBOOK-SANDBOX.md`. A new pattern without an ID and a sandbox entry is unfinished.
 
 ---
 
-## 3. Modifier Syntax & Class Naming Standard
+## 3. CSS naming and modifiers
 
-- **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.
+Full rules: `02-design-system/NAMING-CONVENTIONS.md` and `01-architecture/MODIFIER-SYSTEM.md`.
+
+- **Base name:** short kebab-case: `.p-card`, `.btn`, `.field`.
+- **Element:** double underscore: `.p-card__title`.
+- **Modifier:** a **separate** class starting with a dash: `.-top`, `.-compact`, `.-lg`. Combine freely: `class="p-card -top -compact"`.
+- **Forbidden:** appending a word to a base name (`.btn-lg`, `.card-big`, `.hero-active`). Use `.btn.-lg`.
+- **State:** `is-` prefix: `.is-open`, `.is-active`, `.is-loading`.
+- **Page context:** `body.page-<slug>` set by `usePageSeo`. Override shared components through that class or through CSS custom properties. Never through a new file.
+- **Colour in components:** tokens only (`var(--color-…)`). No raw hex or `rgb()` in component CSS.
+- **Yellow accent (`--color-sun`) is never text.** It is a fill, a badge background or a marker.
 
 ---
 
-## 4. Performance & Core Web Vitals (Target: Lighthouse 95–100)
+## 4. Responsive layout
 
-- **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`.
+- **Components** size themselves with `container-type: inline-size` and `@container`, so they work in any slot.
+- **Pages** use the breakpoints defined in `theme.css` (`--bp-*`). Do not invent new ones.
+- **Grids** that cannot fit on a phone switch to two columns below 900 px, or to one column below 480 px. Check at 390, 820 and 1440 px.
+- **No horizontal scroll** on any page at 390 px. Side gutter is 16 px on phones.
 
 ---
 
-## 5. Assets Pipeline: Tight Trim & Multi-Device Sizing
+## 5. Images and fonts
+
+Full rules: `03-performance-web-vitals/ASSETS-PIPELINE.md`, `FONTS-ZERO-CLS.md`.
 
-- 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.
+- **Every image from `public/` goes through the responsive image component** (`UiImg` in the reference project). Raw `<img src="/…">` is allowed only when the component wraps it.
+- **Explicit `width` and `height`** (or an `aspect-ratio` box) on every image. This gives CLS 0.
+- **Lazy by default.** The single LCP image above the fold is `eager` with `fetchpriority="high"`.
+- **Tight trim:** remove transparent padding before export. Ship WebP (and AVIF where it helps). Generate 1x and 2x variants with the asset script; commit the generated manifest.
+- **One preloaded font weight** on the first screen. Fallback font metrics (`size-adjust`, `ascent-override`, …) so swapping fonts moves nothing.
+- **Missing asset = build error.** Check every `/images/…` and `/fonts/…` reference against `public/` in the QA gate.
 
 ---
 
-## 6. Internationalization (i18n Single Hub)
+## 6. Browser behaviour
 
-- 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.
+- **Media with sound never starts silently on its own.** Autostart only after a real user activation (`pointerdown`, `keydown`, `touchend`) and only if the visitor did not switch it off. Store the visitor's choice explicitly. Probe on reload whether the browser allows playback.
+- **Browser storage is listed** in `docs/ARCHITECTURE.md` (key, value shape, owner). Every read and write is wrapped in `try/catch`. The page must still render when storage is blocked.
+- **Consent** is stored under one key, documented, and respected by every third-party script.
+- **Section navigation** counts only visible sections (`offsetParent !== null`) and recalculates on resize.
+- **Non-critical widgets** (chat, cookie banner, sound, modals) hydrate on idle or on visibility, not on load.
+- **Floating controls** never overlap each other on phones. Offsets come from one variable.
 
 ---
 
-## 7. AI Search & Semantic SEO (AEO / GEO)
+## 7. Internationalisation
+
+Full rules: `05-internationalization/I18N-ARCHITECTURE.md`.
+
+- One hub: `i18n/locales/<code>.ts`. Every locale has the same keys. `i18n-check --strict` must pass.
+- Adding a language = one file plus one entry in the locale list. Nothing else changes.
+- Keys are grouped by component or section (`businessScreens.night.title`). No keys named after pixels or colours.
+
+---
+
+## 8. Accessibility
+
+Full rules: `07-testing/TESTING-STRATEGY.md`.
+
+- **Target:** WCAG 2.2 AA. Axe reports **0 violations** at 390, 820 and 1440 px on every page.
+- **Text contrast:** at least 4.5:1 for body text, 3:1 for large text and UI borders.
+- **Every interactive element** is reachable by keyboard, has a visible focus style and a name.
+- **Icons-only buttons** have an accessible name. Decorative images have `alt=""`.
+- **Contrast is measured**, not estimated, when a palette changes.
+
+---
+
+## 9. SEO and AI search
+
+Full rules: `04-seo-ai-optimization/`.
+
+- Each page: one `<h1>`, a unique title and description, canonical URL, `hreflang` for every locale.
+- Explanatory sections open with a **direct answer block** (40–50 words, factual).
+- Structured data is a single `@graph` (`Organization`, `WebSite`, `Product`, `FAQPage`, `BreadcrumbList` as relevant).
+- **Name, address and phone** in structured data match the business profile exactly. Use placeholders in the standard itself; never real contact data in `ds7/`.
+
+---
+
+## 10. Quality gates and metrics
+
+- **Gates** are commands that must pass before a commit is called done: unit tests, type check, i18n parity, asset references, HTML validity, console errors, axe.
+- **Performance and Web Vitals numbers** in `SPEC.md` are **targets**.
+- **Measured values** go to a dated reference (`docs/METRICS.md`) with the machine, browser and build used. Sandbox or CI numbers are not evidence for LCP or INP. Measure those on a real device.
+- Never write "Lighthouse 100/100" or similar as a fact in code, docs or UI.
+
+---
+
+## 11. Git and releases
+
+- **Commit only when the owner asks, or when the task is explicitly "commit".** Never push unless the owner asks for it.
+- **Small commits**, one concern each. Subject in imperative mood, under 72 characters. Body explains *why*.
+- **Trailers:** commit trailers (for example `Co-Authored-By`) come from the project owner's instructions. If none are given, add none.
+- **Do not commit** generated files unless the project lists them as tracked artifacts. Do not commit `node_modules/`, `.nuxt/`, `.output/`, logs or screenshots.
+- **Semantic versioning** for this package:
+  - `PATCH` (1.1.x): fixes and wording, no change to what the CLI copies.
+  - `MINOR` (1.x.0): new rules, new docs, new template options. Existing projects keep working.
+  - `MAJOR` (x.0.0): renamed IDs, removed rules, changed file layout, changed CLI behaviour.
+- **Every user-visible change adds a line to `CHANGELOG.md`** under `Unreleased`, in Keep a Changelog format. Release = move the section to a version, bump `package.json`, commit, tag `vX.Y.Z`.
+- **Publishing** to npm is done by the maintainer only.
+
+---
+
+## 12. Dependencies and environments
+
+- **Do not install packages into the owner's working copy** just to check something. Use an isolated copy, or ask.
+- **Platform-specific binaries** (native modules) break when `node_modules` is shared between macOS and Linux. Build in a separate copy with its own `node_modules`.
+- **Pin major versions** of framework modules that break easily (for example `@nuxtjs/i18n`). Do not accept a lockfile change that moves them without a reason in the commit message.
+- **Never edit `node_modules`.**
+
+---
+
+## 13. Testing
+
+Full rules: `07-testing/TESTING-STRATEGY.md`.
+
+- Test names state the behaviour: `it('caps savings at the full bill')`, not `it('works')`.
+- Test domain logic and composables. Do not unit-test static data, copy or CSS.
+- During a task run **one targeted test**. Run the full suite once at the end.
+- A test that is skipped or disabled must say why, in the same line.
+
+---
+
+## 14. Documentation
+
+- Each rule has one home. Do not repeat a rule in several files; link to the home.
+- Docs describe the current state. Decisions and their reasons go to `docs/DECISIONS.md` with a date.
+- When behaviour changes, update the doc in the same commit.
+
+---
+
+## 15. Token economy (for agents)
+
+Full strategy: `08-token-optimization/TOKEN-STRATEGY.md`.
+
+1. Read `ALL.md`, then `docs/ARCHITECTURE.md` (the layer map), then only the files on the call chain of the task.
+2. Use the component IDs and the sandbox (`/ui`) instead of long descriptions.
+3. Put one-line file summaries at the top of non-trivial files.
+4. Do not re-read a file you just edited unless the edit tool failed.
+5. Do not start long processes in the background unless the task needs them.
+
+---
 
-- 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`).
+## 16. Quick reference
+
+| ID | Pattern | Where |
+|---|---|---|
+| `BTN-01` | Primary button (sun fill) | `02-design-system/BRANDBOOK-SANDBOX.md` |
+| `BTN-02` | Outline button | same |
+| `CTL-01` | Segmented switch | same |
+| `COUNTER-01` | Bounded numeric counter with − / + | same |
+| `PRICE-01` | Formatted price | same |
+| `CARD-01` | Product card | same |
+| `CARD-02` | Plan / tariff card | same |
+| `SLD-01` | Card slider with scroll-snap | same |
+| `HOOK-01` | Overlap hook under the cover | same |
+
+**Before you finish any task, check:** no hard-coded UI text · no raw colours · no copied component · every image sized and routed through the image component · i18n keys in all locales · axe clean at 390 / 820 / 1440 · CHANGELOG line added · no junk left in the repo.

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to DS7 are recorded here. Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versions follow [Semantic Versioning](https://semver.org/).
+
+## [2.0.0] — 2026-11-14
+
+### Added
+- DS7 is the `ds7` pack of AI-ALL. `init` and `update` enable and refresh it.
+- Integration test against AI-ALL, `.editorconfig`, one shared `.gitignore`.
+- Brand-first build order and English-only documents.
+
+### Changed
+- The root `ALL.md` belongs to AI-ALL. DS7 rules live in `ds7/ALL.md`.
+- The CLI runs the pinned `@ai.all/aiall` 0.3.0.
+- Performance figures are labelled as targets.
+
+### Removed
+- `ALL.project.md`. Project values go in the root `ALL.md`, below the packs block.
+- `ff.md` and `ANDALUSIA.md`, kept in git history.
+
+### Notes
+- 1.1.0 was never published; its changes are part of 2.0.0. Upgrade steps: README, "Upgrading from DS7 1.x".
+
+## [1.0.0] — 2026-11-10
+
+### Added
+- Initial standard: `ALL.md`, `SPEC.md`, `README.md`, folders `01` to `08`, templates, and the `ds7` CLI with `init`, `sync` and `update`.

package/README.md

@@ -1,124 +1,119 @@
-# DS7 · AI-Ready Web Architecture Standard
+# DS7
 
-[![npm](https://img.shields.io/npm/v/@ai-all-ai/ds7)](https://www.npmjs.com/package/@ai-all-ai/ds7)
+[![npm](https://img.shields.io/npm/v/@ai.all/ds7)](https://www.npmjs.com/package/@ai.all/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.**
+> **Brand first, then components, then pages.** A web architecture standard that AI agents can follow without long briefings.
 
 ```bash
-npx @ai-all-ai/ds7
+npx @ai.all/ds7
 ```
 
-Это единственная команда, которая нужна для старта нового проекта:  
-копирует стандарт DS7, создаёт `ALL.md` и синхронизирует все AI-агенты через `@ai.all/aiall`.
+DS7 is a set of rules, templates and reference documents for fast, multilingual Nuxt 4 / Vue 3 sites. Agents read the rules in `ALL.md` first.
 
----
+## Related
 
-> *Универсальная портативная методология для создания сверхбыстрых, масштабируемых веб-приложений на Vue 3 / Nuxt 4 с полной поддержкой AI-агентов, Atomic Design и Core Web Vitals 100/100.*
+- **npm:** [@ai.all/ds7](https://www.npmjs.com/package/@ai.all/ds7)
+- **GitHub:** [ai-all-ai/ds7](https://github.com/ai-all-ai/ds7)
+- **Delivered by:** [AI-ALL](https://github.com/ai-all-ai/aiall) (`@ai.all/aiall`) as the `ds7` pack. See [Packs](https://github.com/ai-all-ai/aiall#packs).
 
-Код и структура выстроены так, чтобы любой разработчик или ИИ-агент, заглянув внутрь, увидел безупречный порядок и захотел взять эту методологию за основу в своих проектах.
+## Quick start
 
----
+**New project**
 
-## 🎯 Главные принципы системы
+```bash
+npx @ai.all/ds7
+```
 
-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`). В диалогах и задачах используются короткие метки без длинных описаний.
+**Sync agent entrypoints only**
 
----
+```bash
+npx @ai.all/ds7 sync
+```
 
-## 📁 Структура каталога `ds7/`
+**Update to the installed version**
 
-```
-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
+```bash
+npm i -D @ai.all/ds7@latest
+npx @ai.all/ds7 update
 ```
 
----
+## Commands
 
-## 🚀 Быстрый старт
+| Command | What it does |
+|---|---|
+| `npx @ai.all/ds7` | Copy the standard to `ds7/`, write `ds7/aiall-pack.json`, run `aiall init`, enable the `ds7` pack |
+| `npx @ai.all/ds7 sync` | Run `aiall sync`; restores missing entrypoints, keeps existing files |
+| `npx @ai.all/ds7 update` | Overwrite `ds7/` and `ds7/aiall-pack.json` with this version, then run `aiall sync`. Project text in the root `ALL.md` is kept |
+| `npx @ai.all/ds7 --version` | Print the version |
+| `npx @ai.all/ds7 --help` | Print usage |
 
-### Вариант А — npm (рекомендуется)
+## Files
 
-```bash
-# В корне нового проекта:
-npx @ai-all-ai/ds7
-```
+| File | Owner | `init` | `update` |
+|---|---|---|---|
+| `ds7/**` | the standard | copies, keeps existing | overwrites |
+| `ds7/aiall-pack.json` | the CLI, generated from its version | creates | overwrites |
+| `ds7/VERSION` | the CLI | writes | writes |
+| `ALL.md` (root) | AI-ALL; the text below the packs block is yours | created by AI-ALL | not changed by DS7 |
+| `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, ... | AI-ALL | created by AI-ALL | not changed by DS7 |
 
-Команда сделает всё:
-- скопирует папку `ds7/` со всем стандартом
-- создаст `ALL.md` (если его нет)
-- запустит `npx @ai.all/aiall` для синхронизации всех AI-агентов
+Put project values in the root `ALL.md`, below the AI-ALL packs block. Edits to `ds7/` are lost on `update`; propose a change to the standard instead.
 
-### Вариант Б — вручную
+## Upgrading from DS7 1.x
 
-1. Скопируйте папку `ds7/` в корень нового проекта
-2. Скопируйте файлы из `ds7/templates/` → `components/`, `assets/css/`, `nuxt.config.ts`
-3. Запустите `npx @ai.all/aiall` для синхронизации AI-агентов
-4. Откройте `/ui` в браузере — интерактивная дизайн-система
+DS7 1.x wrote `ALL.md` and `ALL.project.md` to the project root. From this version the standard is the `ds7` pack of AI-ALL. `update` does not delete or rewrite your files, and it prints a warning for each one that needs a manual step:
 
-### Дополнительные команды
+1. Move the project values from `ALL.project.md` into the root `ALL.md`, below the packs block.
+2. Delete `ALL.project.md`.
+3. In the root `ALL.md`, remove the copied DS7 rules and keep the packs block.
+4. Run `npx @ai.all/ds7 update` and then `npx @ai.all/aiall check`.
 
-```bash
-npx @ai-all-ai/ds7 sync    # синхронизировать только агентов
-npx @ai-all-ai/ds7 update  # обновить ds7/ до последней версии пакета
-npx @ai-all-ai/ds7 --version
-```
+## Build order
+
+1. **Foundations:** tokens in `theme.css`.
+2. **Brandbook:** every token and base atom on `/ui`.
+3. **Atoms and molecules,** built from the brandbook.
+4. **Sections and pages,** built from components.
+
+A value that is not a token does not appear in a component. A pattern that is not in the brandbook is not finished.
+
+## What you get
+
+| Folder | Purpose |
+|---|---|
+| `ALL.md` | Agent contract: rules, build order, checklist, quick reference of component IDs |
+| `SPEC.md` | Technical baseline: stack, directory layout, naming, quality gates |
+| `01-architecture/` | Atomic Design levels, modifier system, component anatomy |
+| `02-design-system/` | Tokens, naming, brandbook sandbox with stable component IDs |
+| `03-performance-web-vitals/` | Assets pipeline, critical CSS, font metrics, hydration |
+| `04-seo-ai-optimization/` | Answer blocks for AI search, structured data, local search |
+| `05-internationalization/` | One locale hub, adding a language |
+| `06-business-conversion/` | Commercial patterns for solar and EV projects (examples) |
+| `07-testing/` | Targeted testing, accessibility gate |
+| `08-token-optimization/` | Working efficiently with AI context |
+| `templates/` | Starter component, tokens, Nuxt config |
+
+## Release
+
+Versioning, release steps and rules: [docs/RELEASE.md](docs/RELEASE.md). The change history is in [CHANGELOG.md](CHANGELOG.md).
+
+## Language
+
+All documents are in English. The owner may converse in any language; code and docs stay in English, UI copy goes through the i18n files.
+
+## Note on examples
+
+`06-business-conversion/` and the example values in `04-seo-ai-optimization/` describe a Spanish solar company. They show structure, not facts to reuse. Replace contact details, legal names and prices with your own.
+
+## Prior art
+
+- Atomic Design by Brad Frost: component levels.
+- W3C Design Tokens Community Group: token file format.
+- Style Dictionary: one token source, many platform outputs.
+- Storybook and public design systems (GOV.UK, Material, Salesforce Lightning): foundations documented before components.
+
+## License
+
+MIT. See [LICENSE](LICENSE).