diff --git a/.gitignore b/.gitignore
index 09957d3..57f6b28 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,6 +3,7 @@ dist/
public/
test/public/
.tmp/
+skills/artifacts/
*.generated.ts
*.tgz
.DS_Store
diff --git a/README.md b/README.md
index 055a165..63251c7 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,6 @@ A CLI for generating SVG sprites and typed icon components for React and Next.js
- [🇬🇧 Download the English skill (latest)](https://github.com/gromov-sergei/svg-sprites/releases/latest/download/svg-sprites.zip)
- [🇷🇺 Download the Russian skill (latest)](https://github.com/gromov-sergei/svg-sprites/releases/latest/download/svg-sprites-ru.zip)
-- [Verify downloads with SHA-256 checksums](https://github.com/gromov-sergei/svg-sprites/releases/latest/download/SHA256SUMS)
## Navigation
diff --git a/README_RU.md b/README_RU.md
index adbe8bf..20f72f7 100644
--- a/README_RU.md
+++ b/README_RU.md
@@ -12,7 +12,6 @@ CLI для генерации SVG-спрайтов и типизированны
- [🇬🇧 Скачать английский скилл (последняя версия)](https://github.com/gromov-sergei/svg-sprites/releases/latest/download/svg-sprites.zip)
- [🇷🇺 Скачать русский скилл (последняя версия)](https://github.com/gromov-sergei/svg-sprites/releases/latest/download/svg-sprites-ru.zip)
-- [Проверить SHA-256-суммы файлов](https://github.com/gromov-sergei/svg-sprites/releases/latest/download/SHA256SUMS)
## Навигация
diff --git a/docs/en/react-vite.md b/docs/en/react-vite.md
index 1e37cc4..9589037 100644
--- a/docs/en/react-vite.md
+++ b/docs/en/react-vite.md
@@ -83,7 +83,7 @@ TypeScript checks the `icon` value against the file names:
.svg`. SVG path data is not included in JavaScript.
diff --git a/docs/en/react-webpack.md b/docs/en/react-webpack.md
index 15383db..1198ba5 100644
--- a/docs/en/react-webpack.md
+++ b/docs/en/react-webpack.md
@@ -81,7 +81,7 @@ TypeScript checks the `icon` value against the file names:
/
+├── SKILL.md
+├── core/
+│ ├── 00-package-overview.md
+│ ├── 10-mode-selection.md
+│ ├── 20-project-inspection.md
+│ ├── 30-react-next-setup.md
+│ ├── 40-generated-contract.md
+│ ├── 50-usage-and-colors.md
+│ ├── 60-verification.md
+│ └── 70-diagnostics.md
+└── references/
+ ├── react-vite.md
+ ├── react-webpack.md
+ ├── next-app.md
+ ├── next-pages.md
+ ├── legacy.md
+ ├── migration-1.md
+ ├── programmatic-api.md
+ └── complex-svg.md
+```
+
+`core/` содержит обязательные знания, раскрываемые прямо в итоговый `SKILL.md`. `references/` содержит самостоятельные инструкции для агента по конкретным стекам и редким сценариям. Пользовательские `README*.md` и `docs/{en,ru}/*.md` дополнительно копируются в `references/upstream/` как вторичный источник полного публичного API.
+
+## Композиция Markdown
+
+В любой собираемый документ можно включать фрагменты:
+
+```md
+
+```
+
+Include раскрываются рекурсивно, путь считается относительно включающего файла. Циклы, отсутствующие файлы, выход за `skills/svg-sprites/`, frontmatter во фрагментах и нераскрытые include завершают сборку ошибкой. Заголовки не сдвигаются автоматически: entry содержит единственный `# H1`, inline-фрагменты начинаются с `##`.
+
+## Локальная сборка
```bash
npm run build:skill
-npm run check:skill
```
-`build:skill` обновляет оба артефакта, а `check:skill` без изменения файлов проверяет их содержимое и синхронность с документацией. Версия без суффикса использует английский язык, версия с суффиксом `-ru` — русский.
+Команда собирает и валидирует обе языковые версии, затем записывает их в игнорируемый каталог `skills/artifacts/`. Сборщик проверяет точный список файлов, безопасные пути, symlink, Markdown fences, локальные ссылки и anchors, единственный H1, frontmatter, размер основного документа и отсутствие `TODO`.
diff --git a/skills/artifacts/svg-sprites-ru/SKILL.md b/skills/artifacts/svg-sprites-ru/SKILL.md
deleted file mode 100644
index b5ff569..0000000
--- a/skills/artifacts/svg-sprites-ru/SKILL.md
+++ /dev/null
@@ -1,64 +0,0 @@
----
-name: svg-sprites-ru
-description: "Используй при настройке, генерации, миграции или диагностике SVG-спрайтов через @gromlab/svg-sprites. Триггеры: SVG sprite, SVG-спрайт, svg-sprites, svg-sprite.config.ts, svg-sprites.config.ts, defineReactSpriteConfig, defineNextSpriteConfig, react@vite, react@webpack, next@app, next@pages, inputFiles, SpriteViewer, icon=\"...\", --icon-color-N, generated-компонент или иконка не появилась в превью и автодополнении. НЕ используй для favicon, растровых изображений, icon fonts, выбора набора иконок или inline SVG без спрайтов."
----
-
-
-
-# SVG Sprites
-
-## Назначение
-
-Используй этот скил для работы с `@gromlab/svg-sprites`: первичной настройки, добавления и переиспользования иконок, генерации React-компонентов, подключения `SpriteViewer`, миграции legacy-конфигурации и диагностики ошибок.
-
-Не навязывай проекту конкретную архитектуру каталогов. Сначала изучи существующие `package.json`, конфигурацию спрайта, используемый фреймворк, роутер и сборщик.
-
-## Рабочий алгоритм
-
-1. Определи существующий режим и не смешивай его API с другим режимом.
-2. Для React выбери `react@vite` или `react@webpack` и открой соответствующий reference.
-3. Для Next.js определи App Router или Pages Router, затем Turbopack или Webpack, и открой соответствующий reference.
-4. Для существующего `svg-sprites.config.ts` с несколькими спрайтами используй legacy-документацию. Не мигрируй такой проект без явного запроса.
-5. Изучи локальные scripts и добавляй генерацию перед `dev`, `build` и `typecheck`, если generated-файлы не хранятся в Git.
-6. После изменения конфигурации или SVG запусти генерацию, затем доступную проверку типов или сборку проекта.
-
-## Правила React и Next.js
-
-- Используй локальный `svg-sprite.config.ts` и подходящий config helper: `defineReactSpriteConfig` или `defineNextSpriteConfig`.
-- Не редактируй `generated/`, `index.ts`, `manifest.ts` и созданный генератором `.gitignore` вручную.
-- Имена исходных SVG становятся допустимыми значениями prop `icon`; используй generated-компонент и его публичные типы вместо deep imports.
-- Объединяй локальную папку и `inputFiles`, когда общая иконка нужна нескольким спрайтам. Не создавай копии одного SVG без необходимости.
-- В Next.js generated-компонент можно использовать в Server Components, SSR и SSG. Не добавляй `'use client'` только ради иконки.
-- Спрайт должен оставаться внешним asset сборщика: не переносить SVG path-данные в JavaScript и не класть generated-файл вручную в `public`.
-
-## Цвета и трансформации
-
-- По умолчанию генератор удаляет `width` и `height`, заменяет поддерживаемые `fill` и `stroke` на CSS-переменные и добавляет transitions.
-- Для монохромной иконки сначала управляй `color`; для многоцветной используй `--icon-color-N`.
-- Не обещай автоматическую замену цветов внутри внешних stylesheets, gradients, patterns, filters и значений `url(#...)` без проверки результата.
-- CSS-переменные страницы работают при ``, но не проникают внутрь `` отдельной debug-страницей приложения. Передай ему manifests или lazy loaders спрайтов. Viewer поддерживает поиск, светлую и тёмную темы, настройку цветов и примеры React, SVG, IMG и CSS.
-
-`SpriteViewer` является клиентским debug-инструментом и импортируется из `@gromlab/svg-sprites/react`; production-компоненты иконок от него не зависят.
-
-## Диагностика
-
-- Если имя иконки отсутствует в автодополнении, проверь входную папку и `inputFiles`, затем перезапусти генерацию.
-- Если два файла имеют одинаковое имя иконки, устрани конфликт вместо выбора одного файла неявно.
-- Если генератор отказывается перезаписывать файл, не удаляй защитный marker и не обходи writer: перенеси пользовательский файл или выбери другой каталог спрайта.
-- Если asset не загружается, сначала проверь соответствие CLI mode реальному сборщику проекта и обработку generated SVG его asset pipeline.
-- Если проект использует старый API, сверь установленную версию пакета и legacy reference перед изменениями.
-
-## References
-
-- [Основная документация и API](./references/README_RU.md)
-- [React + Vite](./references/docs/ru/react-vite.md)
-- [React + Webpack 5](./references/docs/ru/react-webpack.md)
-- [Next.js App Router](./references/docs/ru/next-app.md)
-- [Next.js Pages Router](./references/docs/ru/next-pages.md)
-- [Legacy mode](./references/docs/ru/legacy.md)
-- [Миграция с 0.1.x](./references/docs/ru/migration-1.md)
-- [Программный API](./references/docs/ru/programmatic-api.md)
diff --git a/skills/artifacts/svg-sprites-ru/references/README.md b/skills/artifacts/svg-sprites-ru/references/README.md
deleted file mode 100644
index 055a165..0000000
--- a/skills/artifacts/svg-sprites-ru/references/README.md
+++ /dev/null
@@ -1,405 +0,0 @@
-# @gromlab/svg-sprites
-
-🇬🇧 English | [🇷🇺 Русский](README_RU.md)
-
- 
-
-A CLI for generating SVG sprites and typed icon components for React and Next.js.
-
-
-
-## AI Skills
-
-- [🇬🇧 Download the English skill (latest)](https://github.com/gromov-sergei/svg-sprites/releases/latest/download/svg-sprites.zip)
-- [🇷🇺 Download the Russian skill (latest)](https://github.com/gromov-sergei/svg-sprites/releases/latest/download/svg-sprites-ru.zip)
-- [Verify downloads with SHA-256 checksums](https://github.com/gromov-sergei/svg-sprites/releases/latest/download/SHA256SUMS)
-
-## Navigation
-
-- [AI Skills](#ai-skills)
-- [Features](#features)
-- [Support matrix](#support-matrix)
-- [Requirements](#requirements)
-- [Quick start](#quick-start)
- - [React + Vite](docs/en/react-vite.md)
- - [React + Webpack 5](docs/en/react-webpack.md)
- - [Next.js App Router](docs/en/next-app.md)
- - [Next.js Pages Router](docs/en/next-pages.md)
-- [Configuration](#configuration)
- - [React](#react)
- - [Next.js](#nextjs)
-- [Multiple sprites](#multiple-sprites)
-- [TypeScript](#typescript)
-- [Sprite formats](#sprite-formats)
-- [Rendering methods](#rendering-methods)
-- [Transformations](#transformations)
-- [Icon color management](#icon-color-management)
-- [Caching](#caching)
-- [SpriteViewer](#spriteviewer)
-- [Migrating from 0.1.x](docs/en/migration-1.md)
-- [Documentation](#documentation)
-
-## Features
-
-- **AI-agent friendly** - the repository includes a ready-to-use skill with up-to-date documentation for configuring, migrating, and troubleshooting `@gromlab/svg-sprites`.
-- **TypeScript-friendly** - typed React components, union types, and runtime lists of available icons.
-- **Clean generation** - generated files are automatically excluded from Git, the sprite does not need to be placed in `public` manually, and the generator updates only files it owns.
-- **Shared icons without copying** - SVGs from the local folder and `inputFiles` are merged into a single sprite; one file can be used in multiple sprites.
-- **Built-in interactive preview** - `` is integrated as an application page and displays the provided React and Next.js sprites with search, color controls, and usage examples.
-- **Configurable SVG transformations** - remove `width` and `height` while preserving `viewBox`, replace source colors with CSS variables, and add transitions for `fill` and `stroke`.
-- **Separate cacheable SVG asset** - SVG path data does not end up in JavaScript chunks, and the bundler emits a file with a content hash.
-- **Multiple sprites** - independent React and Next.js modules with their own components, types, and SVG assets.
-- **Server-first Next.js** - generated components work in Server Components, SSR, and SSG without the `'use client'` directive.
-- **Formats for different use cases** - React and Next.js use `stack`; legacy mode also supports `symbol` for existing integrations.
-
-## Support matrix
-
-| Environment | API mode key | Status |
-|---|---|---|
-| React + Vite | `react@vite` | Ready |
-| React + Webpack 5 | `react@webpack` | Ready |
-| Next.js 16.2+ App Router + Turbopack | `next@app/turbopack` | Ready |
-| Next.js 13.4+ App Router + Webpack 5 | `next@app/webpack` | Ready |
-| Next.js 16.2+ Pages Router + Turbopack | `next@pages/turbopack` | Ready |
-| Next.js 12.2+ Pages Router + Webpack 5 | `next@pages/webpack` | Ready |
-| Vue | - | Coming soon |
-| Standalone | - | Coming soon |
-
-## Requirements
-
-- Node.js 18 or newer;
-- the package is distributed as ESM only and is loaded via `import`;
-- React 18 or 19 is required only for generated components and the `@gromlab/svg-sprites/react` entry point;
-- for subpath export typings, use TypeScript 5+ with `moduleResolution: "bundler"`, `"node16"`, or `"nodenext"`.
-
-## Quick start
-
-For a quick start, follow the guide for your stack:
-
-- [React + Vite](docs/en/react-vite.md)
-- [React + Webpack 5](docs/en/react-webpack.md)
-- [Next.js App Router](docs/en/next-app.md)
-- [Next.js Pages Router](docs/en/next-pages.md)
-
-## Configuration
-
-### React
-
-```ts
-import { defineReactSpriteConfig } from '@gromlab/svg-sprites'
-
-export default defineReactSpriteConfig({
- name: 'file-manager',
- description: 'File manager icons',
- inputFolder: './icons',
- inputFiles: [
- '../../shared/icons/check.svg',
- ],
- transform: {
- removeSize: true,
- replaceColors: true,
- addTransition: true,
- },
- generatedNotice: true,
-})
-```
-
-| Option | Type | Default | Purpose |
-|---|---|---|---|
-| `name` | `string` | Folder name | Name of the sprite, component, and public types |
-| `description` | `string` | None | Description for types and the debug manifest |
-| `inputFolder` | `string` | `./icons` | Folder containing source SVGs, relative to the config |
-| `inputFiles` | `string[]` | `[]` | Additional SVG files, relative to the config |
-| `transform` | `TransformOptions` | All enabled | [Transformation settings](#transformations) for source SVGs |
-| `generatedNotice` | `boolean` | `true` | Full or short warning in generated files |
-
-`inputFolder` and `inputFiles` are merged into a single sprite, so one SVG file can be used in multiple sprites without copying. If the implicit `./icons` folder does not exist but `inputFiles` is populated, generation continues using only the list. An explicitly specified missing folder is an error. Duplicate paths are deduplicated, while different files with the same icon name are treated as an error.
-
-`name` is stored in kebab-case and must start with a Latin letter. The React and Next.js presets produce the `stack` format.
-
-### Next.js
-
-Next.js uses the same `svg-sprite.config.ts` and set of options. For type checking, you can use a dedicated helper:
-
-```ts
-import { defineNextSpriteConfig } from '@gromlab/svg-sprites'
-
-export default defineNextSpriteConfig({
- name: 'file-manager',
- description: 'File manager icons',
- inputFolder: './icons',
-})
-```
-
-The router and bundler are selected through the mode key, so switching between Turbopack and Webpack is always explicitly reflected in the generation command.
-
-## Multiple sprites
-
-An application can contain several independent sprites for different scopes:
-
-**Problem:** one global sprite loads icons that the current screen does not need.
-
-**Solution:** keep shared icons globally, and place icon sets for pages and large components in separate sprites that load alongside them.
-
-```text
-global -> GlobalIcon -> shared application icons
-analytics-page -> AnalyticsPageIcon -> icons for a specific page
-file-manager -> FileManagerIcon -> icons for a large component
-```
-
-- **Global sprite** contains a small set of shared icons used in different parts of the application: navigation, states, and basic actions.
-- **Page sprite** loads with a specific section and does not increase the shared sprite with icons that are not needed anywhere else.
-- **Large component sprite** encapsulates the icon set of a complex UI module, such as a file manager or editor.
-
-Each group gets:
-
-- its own SVG asset;
-- its own typed component;
-- a separate list of icon names;
-- a separate debug manifest;
-- an independent cache lifecycle.
-
-
-## TypeScript
-
-The main feature of the TypeScript API is icon name autocomplete directly in the `icon` prop:
-
-```tsx
-`, the generator creates a stable hash ID.
-
-```text
-folder open.svg -> icon="folder open" -> id="icon-"
-```
-
-For such names, use the generated component or the `id` from the debug manifest. The manual examples below using `#` are suitable only for names that are already safe SVG IDs.
-
-## Sprite formats
-
-`stack` is the more modern format, so it is used by default. Icons can be rendered through ``, ``.
-
-## Rendering methods
-
-### React component - recommended
-
-The generated component provides type safety and icon name autocomplete, and constructs the SVG asset URL itself.
-
-```tsx
-`
-
-A good low-level method that provides full control over dimensions and colors. This is exactly what the React component uses under the hood.
-
-How you obtain `spriteUrl` depends on the bundler.
-
-**Vite:**
-
-```tsx
-import spriteUrl from './svg-sprite/generated/sprite.svg?no-inline'
-```
-
-**Webpack 5:**
-
-```tsx
-const spriteUrl = new URL(
- './svg-sprite/generated/sprite.svg',
- import.meta.url,
-).href
-```
-
-**Next.js with Webpack 5 or Turbopack:**
-
-```tsx
-const spriteUrl = new URL(
- './svg-sprite/generated/sprite.svg',
- import.meta.url,
-).href
-```
-
-After obtaining the URL, the icon is rendered the same way:
-
-```tsx
-
-
-```
-
-Vite, Webpack 5, and Next.js replace the source path with the final hashed asset URL automatically.
-
-### With `` while preserving the existing `viewBox`. The icon size is then set externally. |
-| `replaceColors` | `true` | Replaces `fill` and `stroke` colors with `--icon-color-N`. For a monochrome icon, the fallback becomes `currentColor`; for a multicolor icon, the original colors are preserved. |
-| `addTransition` | `true` | Adds `style="transition:fill 0.3s,stroke 0.3s;"` directly to colored SVG elements. An existing `transition` is not overwritten. |
-
-To disable a transformation, pass `false` for the corresponding option. For more details about the result of `replaceColors`, see [Icon color management](#icon-color-management).
-
-## Icon color management
-
-When color replacement is enabled, the generator analyzes `fill` and `stroke` and converts them to CSS custom properties.
-
-### Monochrome icons
-
-If one color is found, the fallback is replaced with `currentColor`:
-
-```svg
-stroke="var(--icon-color-1, currentColor)"
-```
-
-The color is controlled by the CSS `color` property of the outer `` or its parent.
-
-### Multicolor icons
-
-Each unique color gets a separate variable with the original fallback:
-
-```svg
-fill="var(--icon-color-1, #798198)"
-fill="var(--icon-color-2, #ffffff)"
-fill="var(--icon-color-3, #129d9d)"
-```
-
-The page can override only the required colors:
-
-```css
-.icon {
- --icon-color-1: #4b5563;
- --icon-color-3: #14b8a6;
-}
-```
-
-### Color limitations
-
-- `none`, `transparent`, `inherit`, `unset`, and `initial` are not replaced;
-- colors in `fill`, `stroke`, and inline `style` attributes are handled most reliably;
-- CSS classes and external stylesheets inside the source SVG are not the primary transformation use case;
-- gradients, patterns, filters, and `url(#...)` values require separate verification and may be incompatible with automatic color replacement;
-- page CSS variables are available with ``, but are not available inside `.svg
-```
-
-This provides the following properties:
-
-- the SVG is cached independently of JavaScript;
-- changes to React code do not alter the sprite contents;
-- icon changes produce a new hashed asset;
-- one file is used by every instance of the generated component;
-- SVG path data is absent from JavaScript chunks.
-
-The Vite target prevents inlining through `?no-inline`. The Webpack 5 target uses Asset Modules through `new URL(..., import.meta.url)`.
-
-## SpriteViewer
-
-`SpriteViewer` is a React component for viewing generated sprites inside an application's debug route.
-
-It uses separate manifests and displays:
-
-- sprite groups;
-- the icon list and count;
-- search and the system light/dark theme;
-- a preview modal with the `viewBox` and color variable controls;
-- React, SVG, IMG, and CSS examples with code copying.
-
-Production components do not import debug manifests. How you integrate the Viewer depends on the bundler:
-
-- [React + Vite: automatic `import.meta.glob`](docs/en/react-vite.md#6-add-a-debug-page);
-- [React + Webpack 5: static `import()`](docs/en/react-webpack.md#6-add-a-debug-page);
-- [Next.js App Router](docs/en/next-app.md#5-add-spriteviewer);
-- [Next.js Pages Router](docs/en/next-pages.md#5-add-spriteviewer).
-
-The Viewer is imported from the separate `@gromlab/svg-sprites/react` client entry point and is not included in production icon components.
-
-### Viewer theme
-
-By default, `colorTheme="auto"`: the Viewer follows `prefers-color-scheme` and responds to system theme changes. The application theme can be passed explicitly:
-
-```tsx
-` подключается как страница приложения и показывает переданные React- и Next.js-спрайты с поиском, настройкой цветов и примерами использования.
-- **Настраиваемые трансформации SVG** — удаление `width` и `height` с сохранением `viewBox`, замена исходных цветов на CSS-переменные и transitions для `fill` и `stroke`.
-- **Отдельный кешируемый SVG asset** — SVG path-данные не попадают в JavaScript chunks, а сборщик выпускает файл с content hash.
-- **Множественные спрайты** — независимые React- и Next.js-модули со своими компонентами, типами и SVG assets.
-- **Server-first Next.js** — generated-компоненты работают в Server Components, SSR и SSG без директивы `'use client'`.
-- **Форматы под разные сценарии** — React и Next.js используют `stack`, legacy-режим также поддерживает `symbol` для существующих интеграций.
-
-## Таблица поддержки
-
-| Среда | Ключ мода API | Статус |
-|---|---|---|
-| React + Vite | `react@vite` | Готово |
-| React + Webpack 5 | `react@webpack` | Готово |
-| Next.js 16.2+ App Router + Turbopack | `next@app/turbopack` | Готово |
-| Next.js 13.4+ App Router + Webpack 5 | `next@app/webpack` | Готово |
-| Next.js 16.2+ Pages Router + Turbopack | `next@pages/turbopack` | Готово |
-| Next.js 12.2+ Pages Router + Webpack 5 | `next@pages/webpack` | Готово |
-| Vue | — | Скоро |
-| Standalone | — | Скоро |
-
-## Требования
-
-- Node.js 18 или новее;
-- пакет распространяется только как ESM и подключается через `import`;
-- React 18 или 19 требуется только для generated-компонентов и точки входа `@gromlab/svg-sprites/react`;
-- для типизации subpath exports используйте TypeScript 5+ с `moduleResolution: "bundler"`, `"node16"` или `"nodenext"`.
-
-## Быстрый старт
-
-Для быстрого старта воспользуйтесь инструкцией для вашего стека:
-
-- [React + Vite](docs/ru/react-vite.md)
-- [React + Webpack 5](docs/ru/react-webpack.md)
-- [Next.js App Router](docs/ru/next-app.md)
-- [Next.js Pages Router](docs/ru/next-pages.md)
-
-## Конфигурация
-
-### React
-
-```ts
-import { defineReactSpriteConfig } from '@gromlab/svg-sprites'
-
-export default defineReactSpriteConfig({
- name: 'file-manager',
- description: 'Иконки файлового менеджера',
- inputFolder: './icons',
- inputFiles: [
- '../../shared/icons/check.svg',
- ],
- transform: {
- removeSize: true,
- replaceColors: true,
- addTransition: true,
- },
- generatedNotice: true,
-})
-```
-
-| Опция | Тип | По умолчанию | Назначение |
-|---|---|---|---|
-| `name` | `string` | Имя папки | Имя спрайта, компонента и публичных типов |
-| `description` | `string` | Нет | Описание для типов и debug-манифеста |
-| `inputFolder` | `string` | `./icons` | Папка с исходными SVG относительно конфига |
-| `inputFiles` | `string[]` | `[]` | Дополнительные SVG-файлы относительно конфига |
-| `transform` | `TransformOptions` | Все включены | [Настройки трансформации](#трансформации) исходных SVG |
-| `generatedNotice` | `boolean` | `true` | Полное либо короткое предупреждение в generated-файлах |
-
-`inputFolder` и `inputFiles` объединяются в один спрайт, поэтому один SVG-файл можно использовать в нескольких спрайтах без копирования. Если неявной папки `./icons` нет, но `inputFiles` заполнен, генерация продолжается только по списку. Явно указанная отсутствующая папка считается ошибкой. Одинаковые пути дедуплицируются, а разные файлы с одинаковым именем иконки считаются ошибкой.
-
-`name` записывается в kebab-case и должно начинаться с латинской буквы. React и Next.js presets создают формат `stack`.
-
-### Next.js
-
-Next.js использует тот же `svg-sprite.config.ts` и набор опций. Для типизации можно использовать отдельный хелпер:
-
-```ts
-import { defineNextSpriteConfig } from '@gromlab/svg-sprites'
-
-export default defineNextSpriteConfig({
- name: 'file-manager',
- description: 'Иконки файлового менеджера',
- inputFolder: './icons',
-})
-```
-
-Роутер и сборщик выбираются через mode key, поэтому переключение между Turbopack и Webpack всегда явно отражено в команде генерации.
-
-## Множественные спрайты
-
-Приложение может содержать несколько независимых спрайтов с разной областью использования:
-
-**Проблема:** один глобальный спрайт загружает иконки, которые текущему экрану не нужны.
-
-**Решение:** общие иконки хранить глобально, а наборы страниц и крупных компонентов — в отдельных спрайтах, загружаемых вместе с ними.
-
-```text
-global → GlobalIcon → общие иконки приложения
-analytics-page → AnalyticsPageIcon → иконки отдельной страницы
-file-manager → FileManagerIcon → иконки крупного компонента
-```
-
-- **Глобальный спрайт** содержит небольшие общие иконки, используемые в разных частях приложения: навигацию, состояния и базовые действия.
-- **Спрайт страницы** загружается вместе с конкретным разделом и не увеличивает общий спрайт иконками, которые больше нигде не нужны.
-- **Спрайт крупного компонента** инкапсулирует собственный набор иконок сложного UI-модуля, например файлового менеджера или редактора.
-
-Каждая группа получает:
-
-- собственный SVG asset;
-- собственный типизированный компонент;
-- отдельный список имён иконок;
-- отдельный debug-манифест;
-- независимый cache lifecycle.
-
-
-## TypeScript
-
-Главная возможность TypeScript API — автодополнение имён иконок непосредственно в prop `icon`:
-
-```tsx
-` генератор создаёт стабильный hash ID.
-
-```text
-folder open.svg → icon="folder open" → id="icon-"
-```
-
-Для таких имён используйте generated-компонент или `id` из debug-манифеста. Ручные примеры ниже с `#<имя>` подходят только для имён, которые уже являются безопасными SVG ID.
-
-## Форматы спрайтов
-
-`stack` — более современный формат, поэтому он используется по умолчанию. Иконки можно отображать через ``, ``.
-
-## Способы отображения
-
-### React-компонент — рекомендуется
-
-Generated-компонент предоставляет типизацию, автодополнение имён иконок и сам формирует URL SVG asset.
-
-```tsx
-`
-
-Хороший низкоуровневый способ с полным управлением размерами и цветами. React-компонент под капотом использует именно его.
-
-Способ получения `spriteUrl` зависит от сборщика.
-
-**Vite:**
-
-```tsx
-import spriteUrl from './svg-sprite/generated/sprite.svg?no-inline'
-```
-
-**Webpack 5:**
-
-```tsx
-const spriteUrl = new URL(
- './svg-sprite/generated/sprite.svg',
- import.meta.url,
-).href
-```
-
-**Next.js с Webpack 5 или Turbopack:**
-
-```tsx
-const spriteUrl = new URL(
- './svg-sprite/generated/sprite.svg',
- import.meta.url,
-).href
-```
-
-После получения URL иконка отображается одинаково:
-
-```tsx
-
-
-```
-
-Vite, Webpack 5 и Next.js сами заменяют исходный путь на итоговый URL asset с hash.
-
-### Через ``, сохраняя существующий `viewBox`. Размер иконки после этого задаётся снаружи. |
-| `replaceColors` | `true` | Заменяет цвета `fill` и `stroke` на `--icon-color-N`. Для одноцветной иконки fallback становится `currentColor`, для многоцветной сохраняются исходные цвета. |
-| `addTransition` | `true` | Добавляет `style="transition:fill 0.3s,stroke 0.3s;"` непосредственно цветным элементам SVG. Существующий `transition` не перезаписывается. |
-
-Чтобы отключить преобразование, передайте для соответствующей опции `false`. Подробнее о результате `replaceColors` — в разделе [«Управление цветом иконок»](#управление-цветом-иконок).
-
-## Управление цветом иконок
-
-При включённой замене цветов генератор анализирует `fill` и `stroke` и преобразует их в CSS custom properties.
-
-### Монохромные иконки
-
-Если найден один цвет, fallback заменяется на `currentColor`:
-
-```svg
-stroke="var(--icon-color-1, currentColor)"
-```
-
-Цветом управляет CSS-свойство `color` внешнего `` или его родителя.
-
-### Многоцветные иконки
-
-Каждый уникальный цвет получает отдельную переменную с исходным fallback:
-
-```svg
-fill="var(--icon-color-1, #798198)"
-fill="var(--icon-color-2, #ffffff)"
-fill="var(--icon-color-3, #129d9d)"
-```
-
-Страница может заменить только необходимые цвета:
-
-```css
-.icon {
- --icon-color-1: #4b5563;
- --icon-color-3: #14b8a6;
-}
-```
-
-### Ограничения цветов
-
-- `none`, `transparent`, `inherit`, `unset` и `initial` не заменяются;
-- цвета в атрибутах `fill`, `stroke` и inline `style` обрабатываются надёжнее всего;
-- CSS-классы и внешние stylesheets внутри исходного SVG не являются основным сценарием трансформации;
-- gradients, patterns, filters и значения `url(#...)` требуют отдельной проверки и могут быть несовместимы с автоматической заменой цветов;
-- CSS-переменные страницы доступны при ``, но недоступны внутри `.svg
-```
-
-Это даёт следующие свойства:
-
-- SVG кешируется независимо от JavaScript;
-- изменение React-кода не меняет содержимое спрайта;
-- изменение иконок создаёт новый hash asset;
-- один файл используется всеми экземплярами generated-компонента;
-- SVG path-данные отсутствуют в JavaScript chunks.
-
-Vite target запрещает inline через `?no-inline`. Webpack 5 target использует Asset Modules через `new URL(..., import.meta.url)`.
-
-## SpriteViewer
-
-`SpriteViewer` — React-компонент для просмотра generated-спрайтов внутри debug-маршрута приложения.
-
-Он использует отдельные манифесты и показывает:
-
-- группы спрайтов;
-- список и количество иконок;
-- поиск и системную светлую/тёмную тему;
-- модальное превью с `viewBox` и настройкой цветовых переменных;
-- примеры React, SVG, IMG и CSS с копированием кода.
-
-Production-компоненты не импортируют debug-манифесты. Способ подключения Viewer зависит от сборщика:
-
-- [React + Vite: автоматический `import.meta.glob`](docs/ru/react-vite.md#6-добавьте-debug-страницу);
-- [React + Webpack 5: статические `import()`](docs/ru/react-webpack.md#6-добавьте-debug-страницу);
-- [Next.js App Router](docs/ru/next-app.md#5-добавьте-spriteviewer);
-- [Next.js Pages Router](docs/ru/next-pages.md#5-добавьте-spriteviewer).
-
-Viewer подключается из отдельной клиентской точки входа `@gromlab/svg-sprites/react` и не попадает в production-компоненты иконок.
-
-### Тема Viewer
-
-По умолчанию `colorTheme="auto"`: Viewer следует `prefers-color-scheme` и реагирует на смену системной темы. Тему приложения можно передать явно:
-
-```tsx
-
-
-```
-
-## 5. Add a package script
-
-```json
-{
- "scripts": {
- "sprites": "svg-sprites --mode legacy .",
- "prebuild": "npm run sprites"
- }
-}
-```
-
-## Multiple sprites
-
-Add multiple entries to `sprites`:
-
-```ts
-sprites: [
- {
- name: 'icons',
- input: 'src/assets/icons',
- format: 'symbol',
- },
- {
- name: 'logos',
- input: 'src/assets/logos',
- format: 'stack',
- },
-]
-```
-
-All output files and the shared `preview.html` will be written to `output`.
-
-## Troubleshooting
-
-- Config not found: make sure `svg-sprites.config.ts` is located in the specified root directory.
-- No icons: check `sprites[].input` and the `.svg` extension.
-- Preview not needed: set `preview: false`.
-
-For programmatic use, see [`generateLegacy`](programmatic-api.md#generatelegacy).
diff --git a/skills/artifacts/svg-sprites-ru/references/docs/en/migration-1.md b/skills/artifacts/svg-sprites-ru/references/docs/en/migration-1.md
deleted file mode 100644
index b53b915..0000000
--- a/skills/artifacts/svg-sprites-ru/references/docs/en/migration-1.md
+++ /dev/null
@@ -1,96 +0,0 @@
-# Migrating from 0.1.x to 1.0
-
-[← Back to home](../../README.md)
-
-Version 1.0 separates local generation for React and Next.js from the centralized legacy mode. The old config cannot be mixed with the new API in a single CLI invocation.
-
-## CLI
-
-The CLI now always requires an explicit `--mode` and a path to the configuration directory:
-
-```text
-svg-sprites
-→ svg-sprites --mode
-```
-
-Choose a mode based on your environment:
-
-| Environment | Mode |
-|---|---|
-| React + Vite | `react@vite` |
-| React + Webpack 5 | `react@webpack` |
-| Next.js App Router + Turbopack | `next@app/turbopack` |
-| Next.js App Router + Webpack 5 | `next@app/webpack` |
-| Next.js Pages Router + Turbopack | `next@pages/turbopack` |
-| Next.js Pages Router + Webpack 5 | `next@pages/webpack` |
-| Centralized legacy setup | `legacy` |
-
-## React and Next.js
-
-Instead of a root-level `svg-sprites.config.ts`, create a local `svg-sprite.config.ts` next to the icon set:
-
-```ts
-import { defineNextSpriteConfig } from '@gromlab/svg-sprites'
-
-export default defineNextSpriteConfig({
- name: 'global',
- inputFolder: './icons',
-})
-```
-
-For regular React, use `defineReactSpriteConfig`. A folder and an explicit list of shared SVG files can be combined using `inputFolder` and `inputFiles`.
-
-The old `publicPath` and `react` options are no longer needed. The generated module is created next to the config and adds its own `.gitignore`, while Vite, Webpack, or Next.js emits the SVG as a separate asset with a content hash.
-
-The `` as a debug page in the application. A separate `preview.html` is available only in legacy mode.
-
-## Legacy mode
-
-If you need to preserve the centralized structure, rename the helper and the format fields:
-
-```ts
-import { defineLegacyConfig } from '@gromlab/svg-sprites'
-
-export default defineLegacyConfig({
- output: 'public/sprites',
- preview: true,
- sprites: [
- {
- name: 'icons',
- input: 'src/assets/icons',
- format: 'stack',
- },
- ],
-})
-```
-
-- `defineConfig` has been replaced with `defineLegacyConfig`;
-- `sprites[].mode` has been renamed to `sprites[].format`;
-- `generate` has been replaced with `generateLegacy`;
-- `loadConfig` has been replaced with `loadLegacyConfig`;
-- `publicPath` and generation of the old shared React component have been removed.
-
-Run:
-
-```bash
-svg-sprites --mode legacy .
-```
-
-## Programmatic API
-
-The package is distributed as ESM only. Replace `require()` with `import`.
-
-`compileSpriteContent` now returns `Promise` so that the public declarations do not require `@types/node` to be installed. In Node.js, the actual result is compatible with APIs that accept `Uint8Array`.
-
-## After migration
-
-1. Remove the old generated files and rules that ignored the entire directory containing the source icons.
-2. Add an explicit generation command before `dev`, `build`, and `typecheck`.
-3. Run generation and type checking.
-4. Check all icons and color variables using `SpriteViewer` or the legacy `preview.html`.
diff --git a/skills/artifacts/svg-sprites-ru/references/docs/en/next-app.md b/skills/artifacts/svg-sprites-ru/references/docs/en/next-app.md
deleted file mode 100644
index 1e334ce..0000000
--- a/skills/artifacts/svg-sprites-ru/references/docs/en/next-app.md
+++ /dev/null
@@ -1,102 +0,0 @@
-# Next.js App Router
-
-[← Back to home](../../README.md)
-
-Two explicit modes are supported:
-
-| Bundler | Mode key | Next.js version |
-|---|---|---|
-| Turbopack | `next@app/turbopack` | 16.2+ |
-| Webpack 5 | `next@app/webpack` | 13.4+ |
-
-## 1. Install the package
-
-```bash
-npm install @gromlab/svg-sprites
-```
-
-## 2. Create a sprite module
-
-```text
-src/ui/file-manager/svg-sprite/
-├── icons/
-│ ├── check.svg
-│ └── folder.svg
-└── svg-sprite.config.ts
-```
-
-```ts
-// src/ui/file-manager/svg-sprite/svg-sprite.config.ts
-import { defineNextSpriteConfig } from '@gromlab/svg-sprites'
-
-export default defineNextSpriteConfig({
- name: 'file-manager',
- description: 'File manager icons',
-})
-```
-
-## 3. Add generation
-
-For Turbopack:
-
-```json
-{
- "scripts": {
- "sprite:file-manager": "svg-sprites --mode next@app/turbopack src/ui/file-manager/svg-sprite",
- "predev": "npm run sprite:file-manager",
- "prebuild": "npm run sprite:file-manager"
- }
-}
-```
-
-For Webpack, replace the mode key with `next@app/webpack`. In Next 13–15, Webpack is used with the regular `next build` command; in Next 16, use `next build --webpack`.
-
-## 4. Use it in a Server Component
-
-The generated component does not contain `'use client'`, so it can be imported directly into `page.tsx` or `layout.tsx`:
-
-```tsx
-import { FileManagerIcon } from '@/ui/file-manager/svg-sprite'
-
-export default function Page() {
- return (
-
-
- )
-}
-```
-
-Next.js emits a separate SVG asset with a content hash. The same generated code is used during SSR and in the browser, with no URL mismatch.
-
-## 5. Add SpriteViewer
-
-The viewer is interactive, so it requires a separate Client Component boundary:
-
-```tsx
-'use client'
-
-import { SpriteViewer } from '@gromlab/svg-sprites/react'
-
-const sources = [
- () => import('@/ui/file-manager/svg-sprite/manifest'),
-]
-
-export default function SpritesPage() {
- return
-
-)
-```
-
-TypeScript checks the `icon` value against the file names:
-
-```tsx
-.svg`. SVG path data is not included in JavaScript.
-
-## 6. Add a debug page
-
-After integrating the icons, you can display all React sprites with `SpriteViewer`:
-
-```tsx
-import { SpriteViewer } from '@gromlab/svg-sprites/react'
-import type { SpriteManifestModule } from '@gromlab/svg-sprites/react'
-
-const sources = import.meta.glob(
- '/src/**/svg-sprite/manifest.ts',
-)
-
-export const IconsDebugPage = () => (
-
-
-)
-```
-
-TypeScript checks the `icon` value against the file names:
-
-```tsx
-
-
-```
-
-## 5. Добавьте package script
-
-```json
-{
- "scripts": {
- "sprites": "svg-sprites --mode legacy .",
- "prebuild": "npm run sprites"
- }
-}
-```
-
-## Несколько спрайтов
-
-Добавьте несколько записей в `sprites`:
-
-```ts
-sprites: [
- {
- name: 'icons',
- input: 'src/assets/icons',
- format: 'symbol',
- },
- {
- name: 'logos',
- input: 'src/assets/logos',
- format: 'stack',
- },
-]
-```
-
-Все результаты и общий `preview.html` будут записаны в `output`.
-
-## Если что-то не работает
-
-- Не найден конфиг: убедитесь, что `svg-sprites.config.ts` находится в переданном корне.
-- Нет иконок: проверьте `sprites[].input` и расширение `.svg`.
-- Не нужен preview: установите `preview: false`.
-
-Для программного запуска используйте [`generateLegacy`](programmatic-api.md#generatelegacy).
diff --git a/skills/artifacts/svg-sprites-ru/references/docs/ru/migration-1.md b/skills/artifacts/svg-sprites-ru/references/docs/ru/migration-1.md
deleted file mode 100644
index 39b15d8..0000000
--- a/skills/artifacts/svg-sprites-ru/references/docs/ru/migration-1.md
+++ /dev/null
@@ -1,96 +0,0 @@
-# Миграция с 0.1.x на 1.0
-
-[← Главная](../../README_RU.md)
-
-Версия 1.0 разделяет локальную генерацию для React и Next.js и централизованный legacy-режим. Старый config нельзя смешивать с новым API в одном вызове CLI.
-
-## CLI
-
-CLI теперь всегда требует явный `--mode` и путь к каталогу конфигурации:
-
-```text
-svg-sprites
-→ svg-sprites --mode
-```
-
-Выберите mode по окружению:
-
-| Окружение | Mode |
-|---|---|
-| React + Vite | `react@vite` |
-| React + Webpack 5 | `react@webpack` |
-| Next.js App Router + Turbopack | `next@app/turbopack` |
-| Next.js App Router + Webpack 5 | `next@app/webpack` |
-| Next.js Pages Router + Turbopack | `next@pages/turbopack` |
-| Next.js Pages Router + Webpack 5 | `next@pages/webpack` |
-| Централизованная старая схема | `legacy` |
-
-## React и Next.js
-
-Вместо корневого `svg-sprites.config.ts` создайте локальный `svg-sprite.config.ts` рядом с набором иконок:
-
-```ts
-import { defineNextSpriteConfig } from '@gromlab/svg-sprites'
-
-export default defineNextSpriteConfig({
- name: 'global',
- inputFolder: './icons',
-})
-```
-
-Для обычного React используйте `defineReactSpriteConfig`. Папку и явный список общих SVG можно объединить через `inputFolder` и `inputFiles`.
-
-Старые `publicPath` и `react` больше не нужны. Generated-модуль создаётся рядом с конфигом, сам добавляет `.gitignore`, а Vite, Webpack или Next.js выпускает SVG как отдельный asset с content hash.
-
-Компонент `` как debug-страницу приложения. Отдельный `preview.html` остаётся только в legacy-режиме.
-
-## Legacy-режим
-
-Если централизованную структуру нужно сохранить, переименуйте helper и поля формата:
-
-```ts
-import { defineLegacyConfig } from '@gromlab/svg-sprites'
-
-export default defineLegacyConfig({
- output: 'public/sprites',
- preview: true,
- sprites: [
- {
- name: 'icons',
- input: 'src/assets/icons',
- format: 'stack',
- },
- ],
-})
-```
-
-- `defineConfig` заменён на `defineLegacyConfig`;
-- `sprites[].mode` переименован в `sprites[].format`;
-- `generate` заменён на `generateLegacy`;
-- `loadConfig` заменён на `loadLegacyConfig`;
-- `publicPath` и генерация старого общего React-компонента удалены.
-
-Запуск:
-
-```bash
-svg-sprites --mode legacy .
-```
-
-## Программный API
-
-Пакет распространяется только как ESM. Замените `require()` на `import`.
-
-`compileSpriteContent` теперь возвращает `Promise`, чтобы публичные декларации не требовали установки `@types/node`. В Node.js фактический результат совместим с API, принимающими `Uint8Array`.
-
-## После миграции
-
-1. Удалите старые generated-файлы и правила, которые игнорировали целиком каталог с исходными иконками.
-2. Добавьте явную команду генерации перед `dev`, `build` и `typecheck`.
-3. Запустите генерацию и проверку типов.
-4. Проверьте все иконки и цветовые переменные через `SpriteViewer` или legacy `preview.html`.
diff --git a/skills/artifacts/svg-sprites-ru/references/docs/ru/next-app.md b/skills/artifacts/svg-sprites-ru/references/docs/ru/next-app.md
deleted file mode 100644
index 06049c6..0000000
--- a/skills/artifacts/svg-sprites-ru/references/docs/ru/next-app.md
+++ /dev/null
@@ -1,102 +0,0 @@
-# Next.js App Router
-
-[← Главная](../../README_RU.md)
-
-Поддерживаются два явных режима:
-
-| Сборщик | Mode key | Версия Next.js |
-|---|---|---|
-| Turbopack | `next@app/turbopack` | 16.2+ |
-| Webpack 5 | `next@app/webpack` | 13.4+ |
-
-## 1. Установите пакет
-
-```bash
-npm install @gromlab/svg-sprites
-```
-
-## 2. Создайте sprite-модуль
-
-```text
-src/ui/file-manager/svg-sprite/
-├── icons/
-│ ├── check.svg
-│ └── folder.svg
-└── svg-sprite.config.ts
-```
-
-```ts
-// src/ui/file-manager/svg-sprite/svg-sprite.config.ts
-import { defineNextSpriteConfig } from '@gromlab/svg-sprites'
-
-export default defineNextSpriteConfig({
- name: 'file-manager',
- description: 'Иконки файлового менеджера',
-})
-```
-
-## 3. Добавьте генерацию
-
-Для Turbopack:
-
-```json
-{
- "scripts": {
- "sprite:file-manager": "svg-sprites --mode next@app/turbopack src/ui/file-manager/svg-sprite",
- "predev": "npm run sprite:file-manager",
- "prebuild": "npm run sprite:file-manager"
- }
-}
-```
-
-Для Webpack замените mode key на `next@app/webpack`. В Next 13–15 Webpack используется обычной командой `next build`, в Next 16 — командой `next build --webpack`.
-
-## 4. Используйте в Server Component
-
-Generated-компонент не содержит `'use client'`, поэтому его можно импортировать непосредственно в `page.tsx` или `layout.tsx`:
-
-```tsx
-import { FileManagerIcon } from '@/ui/file-manager/svg-sprite'
-
-export default function Page() {
- return (
-
-
- )
-}
-```
-
-Next.js выпустит отдельный SVG asset с content hash. Один generated-код используется при SSR и в браузере без расхождения URL.
-
-## 5. Добавьте SpriteViewer
-
-Viewer интерактивен, поэтому для него нужна отдельная Client Component граница:
-
-```tsx
-'use client'
-
-import { SpriteViewer } from '@gromlab/svg-sprites/react'
-
-const sources = [
- () => import('@/ui/file-manager/svg-sprite/manifest'),
-]
-
-export default function SpritesPage() {
- return
-
-)
-```
-
-Значение `icon` проверяется TypeScript по именам файлов:
-
-```tsx
-.svg`. SVG path-данные не попадут в JavaScript.
-
-## 6. Добавьте debug-страницу
-
-После подключения иконок можно вывести все React-спрайты через `SpriteViewer`:
-
-```tsx
-import { SpriteViewer } from '@gromlab/svg-sprites/react'
-import type { SpriteManifestModule } from '@gromlab/svg-sprites/react'
-
-const sources = import.meta.glob(
- '/src/**/svg-sprite/manifest.ts',
-)
-
-export const IconsDebugPage = () => (
-
-
-)
-```
-
-Значение `icon` проверяется TypeScript по именам файлов:
-
-```tsx
-`, but do not propagate into `` as a separate debug page in the application. Pass sprite manifests or lazy loaders to it. The Viewer supports search, light and dark themes, color controls, and React, SVG, IMG, and CSS examples.
-
-`SpriteViewer` is a client-side debug tool imported from `@gromlab/svg-sprites/react`; production icon components do not depend on it.
-
-## Troubleshooting
-
-- If an icon name is missing from autocomplete, check the input folder and `inputFiles`, then rerun generation.
-- If two files have the same icon name, resolve the conflict instead of implicitly selecting one file.
-- If the generator refuses to overwrite a file, do not remove the protection marker or bypass the writer: move the user file or choose another sprite directory.
-- If an asset fails to load, first confirm that the CLI mode matches the project's actual bundler and that its asset pipeline handles the generated SVG.
-- If the project uses the old API, check the installed package version and the legacy reference before making changes.
-
-## References
-
-- [Main documentation and API](./references/README.md)
-- [React + Vite](./references/docs/en/react-vite.md)
-- [React + Webpack 5](./references/docs/en/react-webpack.md)
-- [Next.js App Router](./references/docs/en/next-app.md)
-- [Next.js Pages Router](./references/docs/en/next-pages.md)
-- [Legacy mode](./references/docs/en/legacy.md)
-- [Migrating from 0.1.x](./references/docs/en/migration-1.md)
-- [Programmatic API](./references/docs/en/programmatic-api.md)
diff --git a/skills/artifacts/svg-sprites/references/README.md b/skills/artifacts/svg-sprites/references/README.md
deleted file mode 100644
index 055a165..0000000
--- a/skills/artifacts/svg-sprites/references/README.md
+++ /dev/null
@@ -1,405 +0,0 @@
-# @gromlab/svg-sprites
-
-🇬🇧 English | [🇷🇺 Русский](README_RU.md)
-
- 
-
-A CLI for generating SVG sprites and typed icon components for React and Next.js.
-
-
-
-## AI Skills
-
-- [🇬🇧 Download the English skill (latest)](https://github.com/gromov-sergei/svg-sprites/releases/latest/download/svg-sprites.zip)
-- [🇷🇺 Download the Russian skill (latest)](https://github.com/gromov-sergei/svg-sprites/releases/latest/download/svg-sprites-ru.zip)
-- [Verify downloads with SHA-256 checksums](https://github.com/gromov-sergei/svg-sprites/releases/latest/download/SHA256SUMS)
-
-## Navigation
-
-- [AI Skills](#ai-skills)
-- [Features](#features)
-- [Support matrix](#support-matrix)
-- [Requirements](#requirements)
-- [Quick start](#quick-start)
- - [React + Vite](docs/en/react-vite.md)
- - [React + Webpack 5](docs/en/react-webpack.md)
- - [Next.js App Router](docs/en/next-app.md)
- - [Next.js Pages Router](docs/en/next-pages.md)
-- [Configuration](#configuration)
- - [React](#react)
- - [Next.js](#nextjs)
-- [Multiple sprites](#multiple-sprites)
-- [TypeScript](#typescript)
-- [Sprite formats](#sprite-formats)
-- [Rendering methods](#rendering-methods)
-- [Transformations](#transformations)
-- [Icon color management](#icon-color-management)
-- [Caching](#caching)
-- [SpriteViewer](#spriteviewer)
-- [Migrating from 0.1.x](docs/en/migration-1.md)
-- [Documentation](#documentation)
-
-## Features
-
-- **AI-agent friendly** - the repository includes a ready-to-use skill with up-to-date documentation for configuring, migrating, and troubleshooting `@gromlab/svg-sprites`.
-- **TypeScript-friendly** - typed React components, union types, and runtime lists of available icons.
-- **Clean generation** - generated files are automatically excluded from Git, the sprite does not need to be placed in `public` manually, and the generator updates only files it owns.
-- **Shared icons without copying** - SVGs from the local folder and `inputFiles` are merged into a single sprite; one file can be used in multiple sprites.
-- **Built-in interactive preview** - `` is integrated as an application page and displays the provided React and Next.js sprites with search, color controls, and usage examples.
-- **Configurable SVG transformations** - remove `width` and `height` while preserving `viewBox`, replace source colors with CSS variables, and add transitions for `fill` and `stroke`.
-- **Separate cacheable SVG asset** - SVG path data does not end up in JavaScript chunks, and the bundler emits a file with a content hash.
-- **Multiple sprites** - independent React and Next.js modules with their own components, types, and SVG assets.
-- **Server-first Next.js** - generated components work in Server Components, SSR, and SSG without the `'use client'` directive.
-- **Formats for different use cases** - React and Next.js use `stack`; legacy mode also supports `symbol` for existing integrations.
-
-## Support matrix
-
-| Environment | API mode key | Status |
-|---|---|---|
-| React + Vite | `react@vite` | Ready |
-| React + Webpack 5 | `react@webpack` | Ready |
-| Next.js 16.2+ App Router + Turbopack | `next@app/turbopack` | Ready |
-| Next.js 13.4+ App Router + Webpack 5 | `next@app/webpack` | Ready |
-| Next.js 16.2+ Pages Router + Turbopack | `next@pages/turbopack` | Ready |
-| Next.js 12.2+ Pages Router + Webpack 5 | `next@pages/webpack` | Ready |
-| Vue | - | Coming soon |
-| Standalone | - | Coming soon |
-
-## Requirements
-
-- Node.js 18 or newer;
-- the package is distributed as ESM only and is loaded via `import`;
-- React 18 or 19 is required only for generated components and the `@gromlab/svg-sprites/react` entry point;
-- for subpath export typings, use TypeScript 5+ with `moduleResolution: "bundler"`, `"node16"`, or `"nodenext"`.
-
-## Quick start
-
-For a quick start, follow the guide for your stack:
-
-- [React + Vite](docs/en/react-vite.md)
-- [React + Webpack 5](docs/en/react-webpack.md)
-- [Next.js App Router](docs/en/next-app.md)
-- [Next.js Pages Router](docs/en/next-pages.md)
-
-## Configuration
-
-### React
-
-```ts
-import { defineReactSpriteConfig } from '@gromlab/svg-sprites'
-
-export default defineReactSpriteConfig({
- name: 'file-manager',
- description: 'File manager icons',
- inputFolder: './icons',
- inputFiles: [
- '../../shared/icons/check.svg',
- ],
- transform: {
- removeSize: true,
- replaceColors: true,
- addTransition: true,
- },
- generatedNotice: true,
-})
-```
-
-| Option | Type | Default | Purpose |
-|---|---|---|---|
-| `name` | `string` | Folder name | Name of the sprite, component, and public types |
-| `description` | `string` | None | Description for types and the debug manifest |
-| `inputFolder` | `string` | `./icons` | Folder containing source SVGs, relative to the config |
-| `inputFiles` | `string[]` | `[]` | Additional SVG files, relative to the config |
-| `transform` | `TransformOptions` | All enabled | [Transformation settings](#transformations) for source SVGs |
-| `generatedNotice` | `boolean` | `true` | Full or short warning in generated files |
-
-`inputFolder` and `inputFiles` are merged into a single sprite, so one SVG file can be used in multiple sprites without copying. If the implicit `./icons` folder does not exist but `inputFiles` is populated, generation continues using only the list. An explicitly specified missing folder is an error. Duplicate paths are deduplicated, while different files with the same icon name are treated as an error.
-
-`name` is stored in kebab-case and must start with a Latin letter. The React and Next.js presets produce the `stack` format.
-
-### Next.js
-
-Next.js uses the same `svg-sprite.config.ts` and set of options. For type checking, you can use a dedicated helper:
-
-```ts
-import { defineNextSpriteConfig } from '@gromlab/svg-sprites'
-
-export default defineNextSpriteConfig({
- name: 'file-manager',
- description: 'File manager icons',
- inputFolder: './icons',
-})
-```
-
-The router and bundler are selected through the mode key, so switching between Turbopack and Webpack is always explicitly reflected in the generation command.
-
-## Multiple sprites
-
-An application can contain several independent sprites for different scopes:
-
-**Problem:** one global sprite loads icons that the current screen does not need.
-
-**Solution:** keep shared icons globally, and place icon sets for pages and large components in separate sprites that load alongside them.
-
-```text
-global -> GlobalIcon -> shared application icons
-analytics-page -> AnalyticsPageIcon -> icons for a specific page
-file-manager -> FileManagerIcon -> icons for a large component
-```
-
-- **Global sprite** contains a small set of shared icons used in different parts of the application: navigation, states, and basic actions.
-- **Page sprite** loads with a specific section and does not increase the shared sprite with icons that are not needed anywhere else.
-- **Large component sprite** encapsulates the icon set of a complex UI module, such as a file manager or editor.
-
-Each group gets:
-
-- its own SVG asset;
-- its own typed component;
-- a separate list of icon names;
-- a separate debug manifest;
-- an independent cache lifecycle.
-
-
-## TypeScript
-
-The main feature of the TypeScript API is icon name autocomplete directly in the `icon` prop:
-
-```tsx
-`, the generator creates a stable hash ID.
-
-```text
-folder open.svg -> icon="folder open" -> id="icon-"
-```
-
-For such names, use the generated component or the `id` from the debug manifest. The manual examples below using `#` are suitable only for names that are already safe SVG IDs.
-
-## Sprite formats
-
-`stack` is the more modern format, so it is used by default. Icons can be rendered through ``, ``.
-
-## Rendering methods
-
-### React component - recommended
-
-The generated component provides type safety and icon name autocomplete, and constructs the SVG asset URL itself.
-
-```tsx
-`
-
-A good low-level method that provides full control over dimensions and colors. This is exactly what the React component uses under the hood.
-
-How you obtain `spriteUrl` depends on the bundler.
-
-**Vite:**
-
-```tsx
-import spriteUrl from './svg-sprite/generated/sprite.svg?no-inline'
-```
-
-**Webpack 5:**
-
-```tsx
-const spriteUrl = new URL(
- './svg-sprite/generated/sprite.svg',
- import.meta.url,
-).href
-```
-
-**Next.js with Webpack 5 or Turbopack:**
-
-```tsx
-const spriteUrl = new URL(
- './svg-sprite/generated/sprite.svg',
- import.meta.url,
-).href
-```
-
-After obtaining the URL, the icon is rendered the same way:
-
-```tsx
-
-
-```
-
-Vite, Webpack 5, and Next.js replace the source path with the final hashed asset URL automatically.
-
-### With `` while preserving the existing `viewBox`. The icon size is then set externally. |
-| `replaceColors` | `true` | Replaces `fill` and `stroke` colors with `--icon-color-N`. For a monochrome icon, the fallback becomes `currentColor`; for a multicolor icon, the original colors are preserved. |
-| `addTransition` | `true` | Adds `style="transition:fill 0.3s,stroke 0.3s;"` directly to colored SVG elements. An existing `transition` is not overwritten. |
-
-To disable a transformation, pass `false` for the corresponding option. For more details about the result of `replaceColors`, see [Icon color management](#icon-color-management).
-
-## Icon color management
-
-When color replacement is enabled, the generator analyzes `fill` and `stroke` and converts them to CSS custom properties.
-
-### Monochrome icons
-
-If one color is found, the fallback is replaced with `currentColor`:
-
-```svg
-stroke="var(--icon-color-1, currentColor)"
-```
-
-The color is controlled by the CSS `color` property of the outer `` or its parent.
-
-### Multicolor icons
-
-Each unique color gets a separate variable with the original fallback:
-
-```svg
-fill="var(--icon-color-1, #798198)"
-fill="var(--icon-color-2, #ffffff)"
-fill="var(--icon-color-3, #129d9d)"
-```
-
-The page can override only the required colors:
-
-```css
-.icon {
- --icon-color-1: #4b5563;
- --icon-color-3: #14b8a6;
-}
-```
-
-### Color limitations
-
-- `none`, `transparent`, `inherit`, `unset`, and `initial` are not replaced;
-- colors in `fill`, `stroke`, and inline `style` attributes are handled most reliably;
-- CSS classes and external stylesheets inside the source SVG are not the primary transformation use case;
-- gradients, patterns, filters, and `url(#...)` values require separate verification and may be incompatible with automatic color replacement;
-- page CSS variables are available with ``, but are not available inside `.svg
-```
-
-This provides the following properties:
-
-- the SVG is cached independently of JavaScript;
-- changes to React code do not alter the sprite contents;
-- icon changes produce a new hashed asset;
-- one file is used by every instance of the generated component;
-- SVG path data is absent from JavaScript chunks.
-
-The Vite target prevents inlining through `?no-inline`. The Webpack 5 target uses Asset Modules through `new URL(..., import.meta.url)`.
-
-## SpriteViewer
-
-`SpriteViewer` is a React component for viewing generated sprites inside an application's debug route.
-
-It uses separate manifests and displays:
-
-- sprite groups;
-- the icon list and count;
-- search and the system light/dark theme;
-- a preview modal with the `viewBox` and color variable controls;
-- React, SVG, IMG, and CSS examples with code copying.
-
-Production components do not import debug manifests. How you integrate the Viewer depends on the bundler:
-
-- [React + Vite: automatic `import.meta.glob`](docs/en/react-vite.md#6-add-a-debug-page);
-- [React + Webpack 5: static `import()`](docs/en/react-webpack.md#6-add-a-debug-page);
-- [Next.js App Router](docs/en/next-app.md#5-add-spriteviewer);
-- [Next.js Pages Router](docs/en/next-pages.md#5-add-spriteviewer).
-
-The Viewer is imported from the separate `@gromlab/svg-sprites/react` client entry point and is not included in production icon components.
-
-### Viewer theme
-
-By default, `colorTheme="auto"`: the Viewer follows `prefers-color-scheme` and responds to system theme changes. The application theme can be passed explicitly:
-
-```tsx
-` подключается как страница приложения и показывает переданные React- и Next.js-спрайты с поиском, настройкой цветов и примерами использования.
-- **Настраиваемые трансформации SVG** — удаление `width` и `height` с сохранением `viewBox`, замена исходных цветов на CSS-переменные и transitions для `fill` и `stroke`.
-- **Отдельный кешируемый SVG asset** — SVG path-данные не попадают в JavaScript chunks, а сборщик выпускает файл с content hash.
-- **Множественные спрайты** — независимые React- и Next.js-модули со своими компонентами, типами и SVG assets.
-- **Server-first Next.js** — generated-компоненты работают в Server Components, SSR и SSG без директивы `'use client'`.
-- **Форматы под разные сценарии** — React и Next.js используют `stack`, legacy-режим также поддерживает `symbol` для существующих интеграций.
-
-## Таблица поддержки
-
-| Среда | Ключ мода API | Статус |
-|---|---|---|
-| React + Vite | `react@vite` | Готово |
-| React + Webpack 5 | `react@webpack` | Готово |
-| Next.js 16.2+ App Router + Turbopack | `next@app/turbopack` | Готово |
-| Next.js 13.4+ App Router + Webpack 5 | `next@app/webpack` | Готово |
-| Next.js 16.2+ Pages Router + Turbopack | `next@pages/turbopack` | Готово |
-| Next.js 12.2+ Pages Router + Webpack 5 | `next@pages/webpack` | Готово |
-| Vue | — | Скоро |
-| Standalone | — | Скоро |
-
-## Требования
-
-- Node.js 18 или новее;
-- пакет распространяется только как ESM и подключается через `import`;
-- React 18 или 19 требуется только для generated-компонентов и точки входа `@gromlab/svg-sprites/react`;
-- для типизации subpath exports используйте TypeScript 5+ с `moduleResolution: "bundler"`, `"node16"` или `"nodenext"`.
-
-## Быстрый старт
-
-Для быстрого старта воспользуйтесь инструкцией для вашего стека:
-
-- [React + Vite](docs/ru/react-vite.md)
-- [React + Webpack 5](docs/ru/react-webpack.md)
-- [Next.js App Router](docs/ru/next-app.md)
-- [Next.js Pages Router](docs/ru/next-pages.md)
-
-## Конфигурация
-
-### React
-
-```ts
-import { defineReactSpriteConfig } from '@gromlab/svg-sprites'
-
-export default defineReactSpriteConfig({
- name: 'file-manager',
- description: 'Иконки файлового менеджера',
- inputFolder: './icons',
- inputFiles: [
- '../../shared/icons/check.svg',
- ],
- transform: {
- removeSize: true,
- replaceColors: true,
- addTransition: true,
- },
- generatedNotice: true,
-})
-```
-
-| Опция | Тип | По умолчанию | Назначение |
-|---|---|---|---|
-| `name` | `string` | Имя папки | Имя спрайта, компонента и публичных типов |
-| `description` | `string` | Нет | Описание для типов и debug-манифеста |
-| `inputFolder` | `string` | `./icons` | Папка с исходными SVG относительно конфига |
-| `inputFiles` | `string[]` | `[]` | Дополнительные SVG-файлы относительно конфига |
-| `transform` | `TransformOptions` | Все включены | [Настройки трансформации](#трансформации) исходных SVG |
-| `generatedNotice` | `boolean` | `true` | Полное либо короткое предупреждение в generated-файлах |
-
-`inputFolder` и `inputFiles` объединяются в один спрайт, поэтому один SVG-файл можно использовать в нескольких спрайтах без копирования. Если неявной папки `./icons` нет, но `inputFiles` заполнен, генерация продолжается только по списку. Явно указанная отсутствующая папка считается ошибкой. Одинаковые пути дедуплицируются, а разные файлы с одинаковым именем иконки считаются ошибкой.
-
-`name` записывается в kebab-case и должно начинаться с латинской буквы. React и Next.js presets создают формат `stack`.
-
-### Next.js
-
-Next.js использует тот же `svg-sprite.config.ts` и набор опций. Для типизации можно использовать отдельный хелпер:
-
-```ts
-import { defineNextSpriteConfig } from '@gromlab/svg-sprites'
-
-export default defineNextSpriteConfig({
- name: 'file-manager',
- description: 'Иконки файлового менеджера',
- inputFolder: './icons',
-})
-```
-
-Роутер и сборщик выбираются через mode key, поэтому переключение между Turbopack и Webpack всегда явно отражено в команде генерации.
-
-## Множественные спрайты
-
-Приложение может содержать несколько независимых спрайтов с разной областью использования:
-
-**Проблема:** один глобальный спрайт загружает иконки, которые текущему экрану не нужны.
-
-**Решение:** общие иконки хранить глобально, а наборы страниц и крупных компонентов — в отдельных спрайтах, загружаемых вместе с ними.
-
-```text
-global → GlobalIcon → общие иконки приложения
-analytics-page → AnalyticsPageIcon → иконки отдельной страницы
-file-manager → FileManagerIcon → иконки крупного компонента
-```
-
-- **Глобальный спрайт** содержит небольшие общие иконки, используемые в разных частях приложения: навигацию, состояния и базовые действия.
-- **Спрайт страницы** загружается вместе с конкретным разделом и не увеличивает общий спрайт иконками, которые больше нигде не нужны.
-- **Спрайт крупного компонента** инкапсулирует собственный набор иконок сложного UI-модуля, например файлового менеджера или редактора.
-
-Каждая группа получает:
-
-- собственный SVG asset;
-- собственный типизированный компонент;
-- отдельный список имён иконок;
-- отдельный debug-манифест;
-- независимый cache lifecycle.
-
-
-## TypeScript
-
-Главная возможность TypeScript API — автодополнение имён иконок непосредственно в prop `icon`:
-
-```tsx
-` генератор создаёт стабильный hash ID.
-
-```text
-folder open.svg → icon="folder open" → id="icon-"
-```
-
-Для таких имён используйте generated-компонент или `id` из debug-манифеста. Ручные примеры ниже с `#<имя>` подходят только для имён, которые уже являются безопасными SVG ID.
-
-## Форматы спрайтов
-
-`stack` — более современный формат, поэтому он используется по умолчанию. Иконки можно отображать через ``, ``.
-
-## Способы отображения
-
-### React-компонент — рекомендуется
-
-Generated-компонент предоставляет типизацию, автодополнение имён иконок и сам формирует URL SVG asset.
-
-```tsx
-`
-
-Хороший низкоуровневый способ с полным управлением размерами и цветами. React-компонент под капотом использует именно его.
-
-Способ получения `spriteUrl` зависит от сборщика.
-
-**Vite:**
-
-```tsx
-import spriteUrl from './svg-sprite/generated/sprite.svg?no-inline'
-```
-
-**Webpack 5:**
-
-```tsx
-const spriteUrl = new URL(
- './svg-sprite/generated/sprite.svg',
- import.meta.url,
-).href
-```
-
-**Next.js с Webpack 5 или Turbopack:**
-
-```tsx
-const spriteUrl = new URL(
- './svg-sprite/generated/sprite.svg',
- import.meta.url,
-).href
-```
-
-После получения URL иконка отображается одинаково:
-
-```tsx
-
-
-```
-
-Vite, Webpack 5 и Next.js сами заменяют исходный путь на итоговый URL asset с hash.
-
-### Через ``, сохраняя существующий `viewBox`. Размер иконки после этого задаётся снаружи. |
-| `replaceColors` | `true` | Заменяет цвета `fill` и `stroke` на `--icon-color-N`. Для одноцветной иконки fallback становится `currentColor`, для многоцветной сохраняются исходные цвета. |
-| `addTransition` | `true` | Добавляет `style="transition:fill 0.3s,stroke 0.3s;"` непосредственно цветным элементам SVG. Существующий `transition` не перезаписывается. |
-
-Чтобы отключить преобразование, передайте для соответствующей опции `false`. Подробнее о результате `replaceColors` — в разделе [«Управление цветом иконок»](#управление-цветом-иконок).
-
-## Управление цветом иконок
-
-При включённой замене цветов генератор анализирует `fill` и `stroke` и преобразует их в CSS custom properties.
-
-### Монохромные иконки
-
-Если найден один цвет, fallback заменяется на `currentColor`:
-
-```svg
-stroke="var(--icon-color-1, currentColor)"
-```
-
-Цветом управляет CSS-свойство `color` внешнего `` или его родителя.
-
-### Многоцветные иконки
-
-Каждый уникальный цвет получает отдельную переменную с исходным fallback:
-
-```svg
-fill="var(--icon-color-1, #798198)"
-fill="var(--icon-color-2, #ffffff)"
-fill="var(--icon-color-3, #129d9d)"
-```
-
-Страница может заменить только необходимые цвета:
-
-```css
-.icon {
- --icon-color-1: #4b5563;
- --icon-color-3: #14b8a6;
-}
-```
-
-### Ограничения цветов
-
-- `none`, `transparent`, `inherit`, `unset` и `initial` не заменяются;
-- цвета в атрибутах `fill`, `stroke` и inline `style` обрабатываются надёжнее всего;
-- CSS-классы и внешние stylesheets внутри исходного SVG не являются основным сценарием трансформации;
-- gradients, patterns, filters и значения `url(#...)` требуют отдельной проверки и могут быть несовместимы с автоматической заменой цветов;
-- CSS-переменные страницы доступны при ``, но недоступны внутри `.svg
-```
-
-Это даёт следующие свойства:
-
-- SVG кешируется независимо от JavaScript;
-- изменение React-кода не меняет содержимое спрайта;
-- изменение иконок создаёт новый hash asset;
-- один файл используется всеми экземплярами generated-компонента;
-- SVG path-данные отсутствуют в JavaScript chunks.
-
-Vite target запрещает inline через `?no-inline`. Webpack 5 target использует Asset Modules через `new URL(..., import.meta.url)`.
-
-## SpriteViewer
-
-`SpriteViewer` — React-компонент для просмотра generated-спрайтов внутри debug-маршрута приложения.
-
-Он использует отдельные манифесты и показывает:
-
-- группы спрайтов;
-- список и количество иконок;
-- поиск и системную светлую/тёмную тему;
-- модальное превью с `viewBox` и настройкой цветовых переменных;
-- примеры React, SVG, IMG и CSS с копированием кода.
-
-Production-компоненты не импортируют debug-манифесты. Способ подключения Viewer зависит от сборщика:
-
-- [React + Vite: автоматический `import.meta.glob`](docs/ru/react-vite.md#6-добавьте-debug-страницу);
-- [React + Webpack 5: статические `import()`](docs/ru/react-webpack.md#6-добавьте-debug-страницу);
-- [Next.js App Router](docs/ru/next-app.md#5-добавьте-spriteviewer);
-- [Next.js Pages Router](docs/ru/next-pages.md#5-добавьте-spriteviewer).
-
-Viewer подключается из отдельной клиентской точки входа `@gromlab/svg-sprites/react` и не попадает в production-компоненты иконок.
-
-### Тема Viewer
-
-По умолчанию `colorTheme="auto"`: Viewer следует `prefers-color-scheme` и реагирует на смену системной темы. Тему приложения можно передать явно:
-
-```tsx
-
-
-```
-
-## 5. Add a package script
-
-```json
-{
- "scripts": {
- "sprites": "svg-sprites --mode legacy .",
- "prebuild": "npm run sprites"
- }
-}
-```
-
-## Multiple sprites
-
-Add multiple entries to `sprites`:
-
-```ts
-sprites: [
- {
- name: 'icons',
- input: 'src/assets/icons',
- format: 'symbol',
- },
- {
- name: 'logos',
- input: 'src/assets/logos',
- format: 'stack',
- },
-]
-```
-
-All output files and the shared `preview.html` will be written to `output`.
-
-## Troubleshooting
-
-- Config not found: make sure `svg-sprites.config.ts` is located in the specified root directory.
-- No icons: check `sprites[].input` and the `.svg` extension.
-- Preview not needed: set `preview: false`.
-
-For programmatic use, see [`generateLegacy`](programmatic-api.md#generatelegacy).
diff --git a/skills/artifacts/svg-sprites/references/docs/en/migration-1.md b/skills/artifacts/svg-sprites/references/docs/en/migration-1.md
deleted file mode 100644
index b53b915..0000000
--- a/skills/artifacts/svg-sprites/references/docs/en/migration-1.md
+++ /dev/null
@@ -1,96 +0,0 @@
-# Migrating from 0.1.x to 1.0
-
-[← Back to home](../../README.md)
-
-Version 1.0 separates local generation for React and Next.js from the centralized legacy mode. The old config cannot be mixed with the new API in a single CLI invocation.
-
-## CLI
-
-The CLI now always requires an explicit `--mode` and a path to the configuration directory:
-
-```text
-svg-sprites
-→ svg-sprites --mode
-```
-
-Choose a mode based on your environment:
-
-| Environment | Mode |
-|---|---|
-| React + Vite | `react@vite` |
-| React + Webpack 5 | `react@webpack` |
-| Next.js App Router + Turbopack | `next@app/turbopack` |
-| Next.js App Router + Webpack 5 | `next@app/webpack` |
-| Next.js Pages Router + Turbopack | `next@pages/turbopack` |
-| Next.js Pages Router + Webpack 5 | `next@pages/webpack` |
-| Centralized legacy setup | `legacy` |
-
-## React and Next.js
-
-Instead of a root-level `svg-sprites.config.ts`, create a local `svg-sprite.config.ts` next to the icon set:
-
-```ts
-import { defineNextSpriteConfig } from '@gromlab/svg-sprites'
-
-export default defineNextSpriteConfig({
- name: 'global',
- inputFolder: './icons',
-})
-```
-
-For regular React, use `defineReactSpriteConfig`. A folder and an explicit list of shared SVG files can be combined using `inputFolder` and `inputFiles`.
-
-The old `publicPath` and `react` options are no longer needed. The generated module is created next to the config and adds its own `.gitignore`, while Vite, Webpack, or Next.js emits the SVG as a separate asset with a content hash.
-
-The `` as a debug page in the application. A separate `preview.html` is available only in legacy mode.
-
-## Legacy mode
-
-If you need to preserve the centralized structure, rename the helper and the format fields:
-
-```ts
-import { defineLegacyConfig } from '@gromlab/svg-sprites'
-
-export default defineLegacyConfig({
- output: 'public/sprites',
- preview: true,
- sprites: [
- {
- name: 'icons',
- input: 'src/assets/icons',
- format: 'stack',
- },
- ],
-})
-```
-
-- `defineConfig` has been replaced with `defineLegacyConfig`;
-- `sprites[].mode` has been renamed to `sprites[].format`;
-- `generate` has been replaced with `generateLegacy`;
-- `loadConfig` has been replaced with `loadLegacyConfig`;
-- `publicPath` and generation of the old shared React component have been removed.
-
-Run:
-
-```bash
-svg-sprites --mode legacy .
-```
-
-## Programmatic API
-
-The package is distributed as ESM only. Replace `require()` with `import`.
-
-`compileSpriteContent` now returns `Promise` so that the public declarations do not require `@types/node` to be installed. In Node.js, the actual result is compatible with APIs that accept `Uint8Array`.
-
-## After migration
-
-1. Remove the old generated files and rules that ignored the entire directory containing the source icons.
-2. Add an explicit generation command before `dev`, `build`, and `typecheck`.
-3. Run generation and type checking.
-4. Check all icons and color variables using `SpriteViewer` or the legacy `preview.html`.
diff --git a/skills/artifacts/svg-sprites/references/docs/en/next-app.md b/skills/artifacts/svg-sprites/references/docs/en/next-app.md
deleted file mode 100644
index 1e334ce..0000000
--- a/skills/artifacts/svg-sprites/references/docs/en/next-app.md
+++ /dev/null
@@ -1,102 +0,0 @@
-# Next.js App Router
-
-[← Back to home](../../README.md)
-
-Two explicit modes are supported:
-
-| Bundler | Mode key | Next.js version |
-|---|---|---|
-| Turbopack | `next@app/turbopack` | 16.2+ |
-| Webpack 5 | `next@app/webpack` | 13.4+ |
-
-## 1. Install the package
-
-```bash
-npm install @gromlab/svg-sprites
-```
-
-## 2. Create a sprite module
-
-```text
-src/ui/file-manager/svg-sprite/
-├── icons/
-│ ├── check.svg
-│ └── folder.svg
-└── svg-sprite.config.ts
-```
-
-```ts
-// src/ui/file-manager/svg-sprite/svg-sprite.config.ts
-import { defineNextSpriteConfig } from '@gromlab/svg-sprites'
-
-export default defineNextSpriteConfig({
- name: 'file-manager',
- description: 'File manager icons',
-})
-```
-
-## 3. Add generation
-
-For Turbopack:
-
-```json
-{
- "scripts": {
- "sprite:file-manager": "svg-sprites --mode next@app/turbopack src/ui/file-manager/svg-sprite",
- "predev": "npm run sprite:file-manager",
- "prebuild": "npm run sprite:file-manager"
- }
-}
-```
-
-For Webpack, replace the mode key with `next@app/webpack`. In Next 13–15, Webpack is used with the regular `next build` command; in Next 16, use `next build --webpack`.
-
-## 4. Use it in a Server Component
-
-The generated component does not contain `'use client'`, so it can be imported directly into `page.tsx` or `layout.tsx`:
-
-```tsx
-import { FileManagerIcon } from '@/ui/file-manager/svg-sprite'
-
-export default function Page() {
- return (
-
-
- )
-}
-```
-
-Next.js emits a separate SVG asset with a content hash. The same generated code is used during SSR and in the browser, with no URL mismatch.
-
-## 5. Add SpriteViewer
-
-The viewer is interactive, so it requires a separate Client Component boundary:
-
-```tsx
-'use client'
-
-import { SpriteViewer } from '@gromlab/svg-sprites/react'
-
-const sources = [
- () => import('@/ui/file-manager/svg-sprite/manifest'),
-]
-
-export default function SpritesPage() {
- return
-
-)
-```
-
-TypeScript checks the `icon` value against the file names:
-
-```tsx
-.svg`. SVG path data is not included in JavaScript.
-
-## 6. Add a debug page
-
-After integrating the icons, you can display all React sprites with `SpriteViewer`:
-
-```tsx
-import { SpriteViewer } from '@gromlab/svg-sprites/react'
-import type { SpriteManifestModule } from '@gromlab/svg-sprites/react'
-
-const sources = import.meta.glob(
- '/src/**/svg-sprite/manifest.ts',
-)
-
-export const IconsDebugPage = () => (
-
-
-)
-```
-
-TypeScript checks the `icon` value against the file names:
-
-```tsx
-
-
-```
-
-## 5. Добавьте package script
-
-```json
-{
- "scripts": {
- "sprites": "svg-sprites --mode legacy .",
- "prebuild": "npm run sprites"
- }
-}
-```
-
-## Несколько спрайтов
-
-Добавьте несколько записей в `sprites`:
-
-```ts
-sprites: [
- {
- name: 'icons',
- input: 'src/assets/icons',
- format: 'symbol',
- },
- {
- name: 'logos',
- input: 'src/assets/logos',
- format: 'stack',
- },
-]
-```
-
-Все результаты и общий `preview.html` будут записаны в `output`.
-
-## Если что-то не работает
-
-- Не найден конфиг: убедитесь, что `svg-sprites.config.ts` находится в переданном корне.
-- Нет иконок: проверьте `sprites[].input` и расширение `.svg`.
-- Не нужен preview: установите `preview: false`.
-
-Для программного запуска используйте [`generateLegacy`](programmatic-api.md#generatelegacy).
diff --git a/skills/artifacts/svg-sprites/references/docs/ru/migration-1.md b/skills/artifacts/svg-sprites/references/docs/ru/migration-1.md
deleted file mode 100644
index 39b15d8..0000000
--- a/skills/artifacts/svg-sprites/references/docs/ru/migration-1.md
+++ /dev/null
@@ -1,96 +0,0 @@
-# Миграция с 0.1.x на 1.0
-
-[← Главная](../../README_RU.md)
-
-Версия 1.0 разделяет локальную генерацию для React и Next.js и централизованный legacy-режим. Старый config нельзя смешивать с новым API в одном вызове CLI.
-
-## CLI
-
-CLI теперь всегда требует явный `--mode` и путь к каталогу конфигурации:
-
-```text
-svg-sprites
-→ svg-sprites --mode
-```
-
-Выберите mode по окружению:
-
-| Окружение | Mode |
-|---|---|
-| React + Vite | `react@vite` |
-| React + Webpack 5 | `react@webpack` |
-| Next.js App Router + Turbopack | `next@app/turbopack` |
-| Next.js App Router + Webpack 5 | `next@app/webpack` |
-| Next.js Pages Router + Turbopack | `next@pages/turbopack` |
-| Next.js Pages Router + Webpack 5 | `next@pages/webpack` |
-| Централизованная старая схема | `legacy` |
-
-## React и Next.js
-
-Вместо корневого `svg-sprites.config.ts` создайте локальный `svg-sprite.config.ts` рядом с набором иконок:
-
-```ts
-import { defineNextSpriteConfig } from '@gromlab/svg-sprites'
-
-export default defineNextSpriteConfig({
- name: 'global',
- inputFolder: './icons',
-})
-```
-
-Для обычного React используйте `defineReactSpriteConfig`. Папку и явный список общих SVG можно объединить через `inputFolder` и `inputFiles`.
-
-Старые `publicPath` и `react` больше не нужны. Generated-модуль создаётся рядом с конфигом, сам добавляет `.gitignore`, а Vite, Webpack или Next.js выпускает SVG как отдельный asset с content hash.
-
-Компонент `` как debug-страницу приложения. Отдельный `preview.html` остаётся только в legacy-режиме.
-
-## Legacy-режим
-
-Если централизованную структуру нужно сохранить, переименуйте helper и поля формата:
-
-```ts
-import { defineLegacyConfig } from '@gromlab/svg-sprites'
-
-export default defineLegacyConfig({
- output: 'public/sprites',
- preview: true,
- sprites: [
- {
- name: 'icons',
- input: 'src/assets/icons',
- format: 'stack',
- },
- ],
-})
-```
-
-- `defineConfig` заменён на `defineLegacyConfig`;
-- `sprites[].mode` переименован в `sprites[].format`;
-- `generate` заменён на `generateLegacy`;
-- `loadConfig` заменён на `loadLegacyConfig`;
-- `publicPath` и генерация старого общего React-компонента удалены.
-
-Запуск:
-
-```bash
-svg-sprites --mode legacy .
-```
-
-## Программный API
-
-Пакет распространяется только как ESM. Замените `require()` на `import`.
-
-`compileSpriteContent` теперь возвращает `Promise`, чтобы публичные декларации не требовали установки `@types/node`. В Node.js фактический результат совместим с API, принимающими `Uint8Array`.
-
-## После миграции
-
-1. Удалите старые generated-файлы и правила, которые игнорировали целиком каталог с исходными иконками.
-2. Добавьте явную команду генерации перед `dev`, `build` и `typecheck`.
-3. Запустите генерацию и проверку типов.
-4. Проверьте все иконки и цветовые переменные через `SpriteViewer` или legacy `preview.html`.
diff --git a/skills/artifacts/svg-sprites/references/docs/ru/next-app.md b/skills/artifacts/svg-sprites/references/docs/ru/next-app.md
deleted file mode 100644
index 06049c6..0000000
--- a/skills/artifacts/svg-sprites/references/docs/ru/next-app.md
+++ /dev/null
@@ -1,102 +0,0 @@
-# Next.js App Router
-
-[← Главная](../../README_RU.md)
-
-Поддерживаются два явных режима:
-
-| Сборщик | Mode key | Версия Next.js |
-|---|---|---|
-| Turbopack | `next@app/turbopack` | 16.2+ |
-| Webpack 5 | `next@app/webpack` | 13.4+ |
-
-## 1. Установите пакет
-
-```bash
-npm install @gromlab/svg-sprites
-```
-
-## 2. Создайте sprite-модуль
-
-```text
-src/ui/file-manager/svg-sprite/
-├── icons/
-│ ├── check.svg
-│ └── folder.svg
-└── svg-sprite.config.ts
-```
-
-```ts
-// src/ui/file-manager/svg-sprite/svg-sprite.config.ts
-import { defineNextSpriteConfig } from '@gromlab/svg-sprites'
-
-export default defineNextSpriteConfig({
- name: 'file-manager',
- description: 'Иконки файлового менеджера',
-})
-```
-
-## 3. Добавьте генерацию
-
-Для Turbopack:
-
-```json
-{
- "scripts": {
- "sprite:file-manager": "svg-sprites --mode next@app/turbopack src/ui/file-manager/svg-sprite",
- "predev": "npm run sprite:file-manager",
- "prebuild": "npm run sprite:file-manager"
- }
-}
-```
-
-Для Webpack замените mode key на `next@app/webpack`. В Next 13–15 Webpack используется обычной командой `next build`, в Next 16 — командой `next build --webpack`.
-
-## 4. Используйте в Server Component
-
-Generated-компонент не содержит `'use client'`, поэтому его можно импортировать непосредственно в `page.tsx` или `layout.tsx`:
-
-```tsx
-import { FileManagerIcon } from '@/ui/file-manager/svg-sprite'
-
-export default function Page() {
- return (
-
-
- )
-}
-```
-
-Next.js выпустит отдельный SVG asset с content hash. Один generated-код используется при SSR и в браузере без расхождения URL.
-
-## 5. Добавьте SpriteViewer
-
-Viewer интерактивен, поэтому для него нужна отдельная Client Component граница:
-
-```tsx
-'use client'
-
-import { SpriteViewer } from '@gromlab/svg-sprites/react'
-
-const sources = [
- () => import('@/ui/file-manager/svg-sprite/manifest'),
-]
-
-export default function SpritesPage() {
- return
-
-)
-```
-
-Значение `icon` проверяется TypeScript по именам файлов:
-
-```tsx
-.svg`. SVG path-данные не попадут в JavaScript.
-
-## 6. Добавьте debug-страницу
-
-После подключения иконок можно вывести все React-спрайты через `SpriteViewer`:
-
-```tsx
-import { SpriteViewer } from '@gromlab/svg-sprites/react'
-import type { SpriteManifestModule } from '@gromlab/svg-sprites/react'
-
-const sources = import.meta.glob(
- '/src/**/svg-sprite/manifest.ts',
-)
-
-export const IconsDebugPage = () => (
-
-
-)
-```
-
-Значение `icon` проверяется TypeScript по именам файлов:
-
-```tsx
-`, but do not propagate into `` as a separate debug page in the application. Pass sprite manifests or lazy loaders to it. The Viewer supports search, light and dark themes, color controls, and React, SVG, IMG, and CSS examples.
-
-`SpriteViewer` is a client-side debug tool imported from `@gromlab/svg-sprites/react`; production icon components do not depend on it.
-
-## Troubleshooting
-
-- If an icon name is missing from autocomplete, check the input folder and `inputFiles`, then rerun generation.
-- If two files have the same icon name, resolve the conflict instead of implicitly selecting one file.
-- If the generator refuses to overwrite a file, do not remove the protection marker or bypass the writer: move the user file or choose another sprite directory.
-- If an asset fails to load, first confirm that the CLI mode matches the project's actual bundler and that its asset pipeline handles the generated SVG.
-- If the project uses the old API, check the installed package version and the legacy reference before making changes.
-
-## References
-
-- [Main documentation and API](./references/README.md)
-- [React + Vite](./references/docs/en/react-vite.md)
-- [React + Webpack 5](./references/docs/en/react-webpack.md)
-- [Next.js App Router](./references/docs/en/next-app.md)
-- [Next.js Pages Router](./references/docs/en/next-pages.md)
-- [Legacy mode](./references/docs/en/legacy.md)
-- [Migrating from 0.1.x](./references/docs/en/migration-1.md)
-- [Programmatic API](./references/docs/en/programmatic-api.md)
diff --git a/skills/svg-sprites/src/SKILL_RU.md b/skills/svg-sprites/src/SKILL_RU.md
deleted file mode 100644
index e1a1a78..0000000
--- a/skills/svg-sprites/src/SKILL_RU.md
+++ /dev/null
@@ -1,57 +0,0 @@
-# SVG Sprites
-
-## Назначение
-
-Используй этот скил для работы с `@gromlab/svg-sprites`: первичной настройки, добавления и переиспользования иконок, генерации React-компонентов, подключения `SpriteViewer`, миграции legacy-конфигурации и диагностики ошибок.
-
-Не навязывай проекту конкретную архитектуру каталогов. Сначала изучи существующие `package.json`, конфигурацию спрайта, используемый фреймворк, роутер и сборщик.
-
-## Рабочий алгоритм
-
-1. Определи существующий режим и не смешивай его API с другим режимом.
-2. Для React выбери `react@vite` или `react@webpack` и открой соответствующий reference.
-3. Для Next.js определи App Router или Pages Router, затем Turbopack или Webpack, и открой соответствующий reference.
-4. Для существующего `svg-sprites.config.ts` с несколькими спрайтами используй legacy-документацию. Не мигрируй такой проект без явного запроса.
-5. Изучи локальные scripts и добавляй генерацию перед `dev`, `build` и `typecheck`, если generated-файлы не хранятся в Git.
-6. После изменения конфигурации или SVG запусти генерацию, затем доступную проверку типов или сборку проекта.
-
-## Правила React и Next.js
-
-- Используй локальный `svg-sprite.config.ts` и подходящий config helper: `defineReactSpriteConfig` или `defineNextSpriteConfig`.
-- Не редактируй `generated/`, `index.ts`, `manifest.ts` и созданный генератором `.gitignore` вручную.
-- Имена исходных SVG становятся допустимыми значениями prop `icon`; используй generated-компонент и его публичные типы вместо deep imports.
-- Объединяй локальную папку и `inputFiles`, когда общая иконка нужна нескольким спрайтам. Не создавай копии одного SVG без необходимости.
-- В Next.js generated-компонент можно использовать в Server Components, SSR и SSG. Не добавляй `'use client'` только ради иконки.
-- Спрайт должен оставаться внешним asset сборщика: не переносить SVG path-данные в JavaScript и не класть generated-файл вручную в `public`.
-
-## Цвета и трансформации
-
-- По умолчанию генератор удаляет `width` и `height`, заменяет поддерживаемые `fill` и `stroke` на CSS-переменные и добавляет transitions.
-- Для монохромной иконки сначала управляй `color`; для многоцветной используй `--icon-color-N`.
-- Не обещай автоматическую замену цветов внутри внешних stylesheets, gradients, patterns, filters и значений `url(#...)` без проверки результата.
-- CSS-переменные страницы работают при ``, но не проникают внутрь `` отдельной debug-страницей приложения. Передай ему manifests или lazy loaders спрайтов. Viewer поддерживает поиск, светлую и тёмную темы, настройку цветов и примеры React, SVG, IMG и CSS.
-
-`SpriteViewer` является клиентским debug-инструментом и импортируется из `@gromlab/svg-sprites/react`; production-компоненты иконок от него не зависят.
-
-## Диагностика
-
-- Если имя иконки отсутствует в автодополнении, проверь входную папку и `inputFiles`, затем перезапусти генерацию.
-- Если два файла имеют одинаковое имя иконки, устрани конфликт вместо выбора одного файла неявно.
-- Если генератор отказывается перезаписывать файл, не удаляй защитный marker и не обходи writer: перенеси пользовательский файл или выбери другой каталог спрайта.
-- Если asset не загружается, сначала проверь соответствие CLI mode реальному сборщику проекта и обработку generated SVG его asset pipeline.
-- Если проект использует старый API, сверь установленную версию пакета и legacy reference перед изменениями.
-
-## References
-
-- [Основная документация и API](./references/README_RU.md)
-- [React + Vite](./references/docs/ru/react-vite.md)
-- [React + Webpack 5](./references/docs/ru/react-webpack.md)
-- [Next.js App Router](./references/docs/ru/next-app.md)
-- [Next.js Pages Router](./references/docs/ru/next-pages.md)
-- [Legacy mode](./references/docs/ru/legacy.md)
-- [Миграция с 0.1.x](./references/docs/ru/migration-1.md)
-- [Программный API](./references/docs/ru/programmatic-api.md)
diff --git a/skills/svg-sprites/src/en/SKILL.md b/skills/svg-sprites/src/en/SKILL.md
new file mode 100644
index 0000000..81b117a
--- /dev/null
+++ b/skills/svg-sprites/src/en/SKILL.md
@@ -0,0 +1,19 @@
+# @gromlab/svg-sprites
+
+
+
+
+
+
+
+
+
+
+## References to open as needed
+
+- For React + Vite, open [React + Vite](./references/react-vite.md); for React with a custom Webpack 5 setup, open [React + Webpack](./references/react-webpack.md).
+- For Next.js, open the guide for the [App Router](./references/next-app.md) or [Pages Router](./references/next-pages.md), then select the section for the bundler actually in use.
+- If the project has `svg-sprites.config.ts`, open [legacy mode](./references/legacy.md); when upgrading from `0.1.x`, also open the [migration guide](./references/migration-1.md).
+- To invoke the generator from Node.js, open the [programmatic API](./references/programmatic-api.md).
+- For gradients, filters, `url(#...)`, unusual colors, and `viewBox` issues, open [complex SVGs](./references/complex-svg.md).
+- Use the complete user documentation as a secondary source: [package README](./references/upstream/README.md).
diff --git a/skills/svg-sprites/src/en/core/00-package-overview.md b/skills/svg-sprites/src/en/core/00-package-overview.md
new file mode 100644
index 0000000..7d98aa2
--- /dev/null
+++ b/skills/svg-sprites/src/en/core/00-package-overview.md
@@ -0,0 +1,15 @@
+## What the package does
+
+`@gromlab/svg-sprites` is a CLI generator that builds SVG sprites from user-provided SVG files. The package does not include its own icon set: it compiles the project's SVGs into an external cacheable sprite asset and, for React/Next.js, creates a typed component, a list of valid names, and a debug manifest.
+
+The package supports multiple independent sprites in one project. Each selected directory containing `svg-sprite.config.ts` describes one sprite and gets its own:
+
+- SVG asset;
+- icon name types;
+- React component;
+- production entry point `index.ts`;
+- debug entry point `manifest.ts`.
+
+The project determines how many sprite directories exist and where they live. For example, `name: 'file-manager'` produces `FileManagerIcon`, while another directory with `name: 'navigation'` produces a separate `NavigationIcon`. The names `FileManagerIcon` and `fileManagerIconNames` used below are examples of the API for one possible sprite, not fixed package exports.
+
+Generated production components do not import `@gromlab/svg-sprites` at runtime. For routine generation, run the latest CLI through `npx`; install the package in the project only when `SpriteViewer`, the programmatic API, or a local config helper is required.
diff --git a/skills/svg-sprites/src/en/core/10-mode-selection.md b/skills/svg-sprites/src/en/core/10-mode-selection.md
new file mode 100644
index 0000000..b45030c
--- /dev/null
+++ b/skills/svg-sprites/src/en/core/10-mode-selection.md
@@ -0,0 +1,29 @@
+## Selecting a mode
+
+Select exactly one supported mode key:
+
+| Project | Mode key |
+|---|---|
+| React + Vite | `react@vite` |
+| React + Webpack 5 | `react@webpack` |
+| Next.js App Router + Turbopack | `next@app/turbopack` |
+| Next.js App Router + Webpack 5 | `next@app/webpack` |
+| Next.js Pages Router + Turbopack | `next@pages/turbopack` |
+| Next.js Pages Router + Webpack 5 | `next@pages/webpack` |
+| Existing shared config | `legacy` |
+
+Do not use the incomplete `react`, `next@app`, or `next@pages` keys, the future `standalone` mode, or a mode for a different bundler. The CLI always requires a mode and exactly one path to a configuration directory:
+
+```bash
+npx --yes @gromlab/svg-sprites@latest --mode
+```
+
+Do not pass multiple paths, a glob, or the path to the config file itself. For multiple modern sprites, create a separate command for each directory.
+
+Identify legacy mode by its contract, not by the number of sprites:
+
+- `svg-sprites.config.ts` in the supplied root, with top-level `output` and a non-empty `sprites` array, is a legacy config even if it contains only one entry;
+- each legacy entry uses `name`, `input`, and optional `format: 'stack' | 'symbol'`; the `mode` field is deprecated;
+- a local `svg-sprite.config.ts` in a single sprite directory, with `name`, `description`, `inputFolder`, `inputFiles`, `transform`, and `generatedNotice`, belongs to the React/Next API even when the application has many such sprites.
+
+Do not migrate a legacy config without an explicit request. Do not combine `defineLegacyConfig` or the `output`/`sprites` fields with `defineReactSpriteConfig` or `defineNextSpriteConfig`.
diff --git a/skills/svg-sprites/src/en/core/20-project-inspection.md b/skills/svg-sprites/src/en/core/20-project-inspection.md
new file mode 100644
index 0000000..b9c7cad
--- /dev/null
+++ b/skills/svg-sprites/src/en/core/20-project-inspection.md
@@ -0,0 +1,22 @@
+## Inspecting the project
+
+Establish the project's actual contract before making changes:
+
+1. Read the root `package.json`, lockfile, and workspace configuration; identify the framework, bundler, and existing commands.
+2. Find `svg-sprite.config.ts`, `svg-sprites.config.ts`, commands containing `svg-sprites`, and imports of generated components.
+3. For React, determine whether the project uses Vite or Webpack 5 from its scripts and configuration. For Next.js, separately determine the App/Pages Router and the bundler used by the actual `dev`/`build` commands.
+4. Check existing `predev`, `prebuild`, `pretypecheck`, and orchestration scripts. Do not overwrite them.
+5. For a new sprite, choose a target directory without imposing a particular application layer or architecture.
+6. Check TypeScript and alias settings. Package subpath exports require TypeScript 5+ with `moduleResolution: 'bundler'`, `'node16'`, or `'nodenext'`.
+
+All paths in a modern config are relative to the directory containing `svg-sprite.config.ts`:
+
+- `inputFolder` defaults to `./icons`;
+- `inputFiles` contains additional relative paths to individual SVGs and is merged with `inputFolder`;
+- the same absolute file is deduplicated, but different files with the same icon basename cause an error;
+- scanning `inputFolder` is shallow: only immediate files ending in `.svg` are read, and nested directories are not traversed;
+- an explicitly configured `inputFolder` that does not exist is an error;
+- if `inputFolder` is omitted, `./icons` does not exist, and `inputFiles` is non-empty, generation uses only `inputFiles`;
+- an empty final input set, a missing file, or a path that does not point to an `.svg` file is an error.
+
+Do not copy a shared SVG into several folders: add its relative path to `inputFiles` in every sprite that needs it. If a recursive structure is required, list the files explicitly or reorganize the sources; the generator does not perform recursive scanning.
diff --git a/skills/svg-sprites/src/en/core/30-react-next-setup.md b/skills/svg-sprites/src/en/core/30-react-next-setup.md
new file mode 100644
index 0000000..44e636e
--- /dev/null
+++ b/skills/svg-sprites/src/en/core/30-react-next-setup.md
@@ -0,0 +1,51 @@
+## Setting up React or Next.js
+
+Choose a target directory for one sprite. It may live next to a feature, in a shared icons directory, or anywhere else that follows the project's conventions. The following structure is only an example:
+
+```text
+src/ui/file-manager/svg-sprite/
+├── icons/
+│ ├── check.svg
+│ └── folder.svg
+└── svg-sprite.config.ts
+```
+
+One `svg-sprite.config.ts` creates one independent sprite. For multiple sets, choose multiple directories and assign each a unique `name`.
+
+When running through `npx`, the config may export a plain object without importing the package:
+
+```ts
+export default {
+ name: 'file-manager',
+ description: 'File manager icons',
+ inputFolder: './icons',
+ inputFiles: ['../../shared/icons/close.svg'],
+}
+```
+
+The object contract is the same for React and Next.js. If the package is already installed, the object may be wrapped in `defineReactSpriteConfig(...)` or `defineNextSpriteConfig(...)` for autocomplete. A helper is not required for normal CLI generation.
+
+`name` must begin with an ASCII letter and use kebab-case. The example `file-manager` produces `FileManagerIcon`, `FileManagerIconName`, and `fileManagerIconNames`. Another sprite gets its own names. If `name` is omitted, the generator derives it from the directory.
+
+Add a separate command with the selected mode key and one path:
+
+```json
+{
+ "scripts": {
+ "sprite:file-manager": "npx --yes @gromlab/svg-sprites@latest --mode react@vite src/ui/file-manager/svg-sprite",
+ "sprites": "npm run sprite:file-manager"
+ }
+}
+```
+
+For Next.js, substitute the full key, for example `next@app/turbopack`. For multiple sprites, add one `sprite:` command per directory and invoke them sequentially from `sprites`.
+
+Generated files are excluded from Git by default, so run `sprites` before any process that needs `index.ts`, the types, or the asset. Add it to `predev`, `prebuild`, and, when a `typecheck` script exists, `pretypecheck`.
+
+If a lifecycle script is missing, create it. If it already exists, preserve its command and append generation with `&&`; for example, change `"prebuild": "npm run lint"` to `"prebuild": "npm run lint && npm run sprites"`. Never replace an existing `pre*` script with generation alone, and never create a duplicate JSON key.
+
+Run the first generation manually:
+
+```bash
+npm run sprites
+```
diff --git a/skills/svg-sprites/src/en/core/40-generated-contract.md b/skills/svg-sprites/src/en/core/40-generated-contract.md
new file mode 100644
index 0000000..89c2165
--- /dev/null
+++ b/skills/svg-sprites/src/en/core/40-generated-contract.md
@@ -0,0 +1,34 @@
+## Generated directory contract
+
+After generation, the selected directory has this structure:
+
+```text
+svg-sprite/
+├── icons/ # user-owned sources
+├── svg-sprite.config.ts # user-owned config
+├── .gitignore # managed by the generator
+├── index.ts # public production entry point
+├── manifest.ts # separate debug entry point
+└── generated/
+ ├── .svg-sprites.manifest.json # ownership registry
+ ├── react-component.tsx
+ ├── sprite.svg
+ ├── styles.module.css
+ └── types.ts
+```
+
+Edit only the source SVGs and `svg-sprite.config.ts`. Do not manually change `.gitignore`, `index.ts`, `manifest.ts`, or anything in `generated/`: the next generation will overwrite them. Import the production API from the root `index.ts`, not through a deep import from `generated/`.
+
+The generator owns only the listed root files and immediate files in `generated/`. The `.svg-sprites.manifest.json` registry allows stale generated files to be removed, but the writer refuses to overwrite or delete any file without a generated marker. Do not remove the marker, bypass the refusal, or replace generated paths with symlinks: move the user-owned file or choose a different directory.
+
+The public entry point exports the component, props/style types, a readonly array of names, and the icon-name union type. `manifest.ts` contains the URL, target, icon list, and icon metadata for debug tools and is not imported by the production component.
+
+The sprite remains a separate content-hashed asset; SVG path data is not embedded in JavaScript:
+
+- `react@vite` generates a static `sprite.svg?no-inline` import, preventing Vite from inlining it;
+- React Webpack 5 and all Next modes generate `new URL('./sprite.svg', import.meta.url).href`, which must be processed by the selected bundler's Asset Modules;
+- a custom Webpack SVG loader must not intercept the generated `sprite.svg`;
+- in Next mode, the generated component does not contain `'use client'` and works in Server Components, SSR, and SSG; do not add a client boundary solely for an icon;
+- the Next build command and mode key must agree: Turbopack with `.../turbopack`, Webpack with `.../webpack`.
+
+Do not move the generated sprite into `public` or rewrite its URL manually. When changing the router or bundler, regenerate the sprite with the new full mode key.
diff --git a/skills/svg-sprites/src/en/core/50-usage-and-colors.md b/skills/svg-sprites/src/en/core/50-usage-and-colors.md
new file mode 100644
index 0000000..c839e29
--- /dev/null
+++ b/skills/svg-sprites/src/en/core/50-usage-and-colors.md
@@ -0,0 +1,73 @@
+## Usage, accessibility, and colors
+
+The component name depends on the specific sprite's `name`. These examples use `name: 'file-manager'`, so the generated component is called `FileManagerIcon`. For `name: 'navigation'`, use the generated `NavigationIcon`.
+
+Import the component from the root of its sprite directory. `width` and `height` are optional: ordinary CSS classes can control the size.
+
+```tsx
+import { FileManagerIcon } from './svg-sprite'
+
+export const OpenButton = () => (
+
+ Open
+
+)
+```
+
+```css
+.icon {
+ width: 24px;
+ height: 24px;
+ color: #4b5563;
+}
+```
+
+`icon` accepts exact source filenames without `.svg`; an unknown name is a TypeScript error. For names that are not safe SVG IDs, the generator preserves the public name but creates an internal stable hash ID, so do not construct a fragment URL from the name manually.
+
+By default, the component renders `` and accepts standard SVG attributes: optional `width`/`height`, `className`, `style`, `role`, `aria-*`, and event handlers. With `wrapped={true}`, the root becomes a ``, props apply to the span, and the inner SVG fills the wrapper. This is convenient when a class controls both size and colors:
+
+```tsx
+`, but do not cross into an external document loaded through `` and one sprite directory. |
+| `Expected one sprite path` | Multiple paths were passed | Create one command per modern sprite and combine the scripts. |
+| `React mode requires a target` or `Unsupported Next.js target` | A shortened or unsupported key was used | Select one of the seven mode keys from the table; do not use `standalone`. |
+| `React config file not found` | The CLI path does not point to a directory containing `svg-sprite.config.ts` | Fix the positional path; do not pass the config file itself. |
+| Legacy config is missing or read by the wrong pipeline | `svg-sprites.config.ts` and `svg-sprite.config.ts` were confused | Identify the API by the config filename and fields, regardless of the number of `sprites` entries. |
+| `Input directory does not exist` | The relative path is wrong or an explicitly configured folder is missing | Resolve it from the config directory; create the folder or correct `inputFolder`. |
+| Icons from a subdirectory are missing | Recursive scanning was assumed | Move the SVG to the top level of `inputFolder` or list it in `inputFiles`. |
+| `SVG file does not exist`, `File is not an SVG`, or an empty input set | Invalid `inputFiles`, extension, or sources | Correct the path/extension and provide at least one input SVG. |
+| Icon name or SVG ID collision | Two different files have the same basename, or a hash ID collides with a name | Rename one source SVG; do not select a file implicitly. |
+| `Refusing to overwrite/delete a user file` | A user file occupies a managed path or lost its marker | Do not bypass the protection: move the file or choose another sprite directory and regenerate. |
+| Missing `index.ts` or name absent from autocomplete | Generation did not run after the change, or the type server cached an old module | Run the sprite command, then typecheck; restart the TypeScript server if necessary. |
+| SVG does not load or the URL is wrong | Mode and bundler differ, Webpack `publicPath` is wrong, or a custom loader intercepted the asset | Align mode with the build command, check Asset Modules/`publicPath`, and exclude the generated SVG from the incompatible loader. |
+| Next build differs between SSR and browser | The module targets another bundler/router, or the URL was rewritten manually | Restore the generated `new URL(...)`, select the exact Next mode, and regenerate. |
+| `color` does not change a multicolor icon | The icon uses several variables or is rendered through ``/`` and the required `--icon-color-N` properties. |
+| Gradient/filter renders incorrectly | Automatic color replacement cannot guarantee complex paint servers | Inspect the generated SVG; disable `replaceColors` for the sprite or simplify the source if necessary. |
+| Viewer is empty | Manifests were not generated, the glob/import is not static, or the Client Component boundary is wrong | Generate sprites first; use a literal glob for Vite, static loaders for Webpack/Next, and add `'use client'` only to the App Router Viewer page. |
+
+For an unknown error, record the complete CLI command, mode, config path, and first stack/error message. Then reduce it to one sprite without deleting user files or protective markers.
diff --git a/skills/svg-sprites/src/en/references/complex-svg.md b/skills/svg-sprites/src/en/references/complex-svg.md
new file mode 100644
index 0000000..213ea02
--- /dev/null
+++ b/skills/svg-sprites/src/en/references/complex-svg.md
@@ -0,0 +1,173 @@
+# Complex SVGs: diagnostics and safe generation
+
+## When to use this reference
+
+Use this document when a source contains ``, gradients, patterns, filters, masks, clip paths, internal `