@bonesofspring/ai-rules 0.2.13 → 0.2.15

package/presets/claude/next/rules/ui-and-accessibility/react-a11y-coding.md

@@ -4,34 +4,34 @@ paths:
   - app/src/ui/**/*.ts
 ---
 
-# A11y при разработке UI
+# A11y while building UI
 
-Reviewer (`accessibility-reviewer`) проверяет diff; эти правила — **при написании** кода.
+The reviewer (`accessibility-reviewer`) checks the diff; these rules apply **while writing** code.
 
-## Семантика и ARIA
+## Semantics and ARIA
 
-- Предпочитать **нативные элементы** (`button`, `a`, `label`, `input`) вместо `div` с `onClick`.
-- **`role` / `aria-*`** — только когда нативного аналога нет; не дублировать то, что даёт семантика.
-- Заголовки — иераархия `h1`–`h6` без пропусков уровней ради стилей.
+- Prefer **native elements** (`button`, `a`, `label`, `input`) over `div` with `onClick`.
+- **`role` / `aria-*`** — only when no native equivalent exists; do not duplicate what semantics already provide.
+- Headings — `h1`–`h6` hierarchy without skipping levels for styling.
 
-## Формы
+## Forms
 
-- Каждый input связан с **`label`** (`htmlFor` / `id` или обёртка).
-- Сообщения об ошибках — **`aria-describedby`**, `aria-invalid` при validation errors.
-- Кнопки submit vs button — явный `type`.
+- Every input is associated with a **`label`** (`htmlFor` / `id` or wrapper).
+- Error messages — **`aria-describedby`**, `aria-invalid` on validation errors.
+- Submit vs button — explicit `type`.
 
-## Клавиатура и focus
+## Keyboard and focus
 
-- Все интерактивные элементы **достижимы с Tab** и активируются Enter/Space где ожидается.
-- **Modals/drawers** — focus trap, возврат focus на trigger при закрытии, Esc закрывает (если по UX).
-- Не удалять видимый **focus outline** без замены на доступный custom focus style.
+- All interactive elements are **reachable via Tab** and activate with Enter/Space where expected.
+- **Modals/drawers** — focus trap, return focus to trigger on close, Esc closes (if UX allows).
+- Do not remove visible **focus outline** without an accessible custom focus style.
 
-## Контент
+## Content
 
-- Изображения — **`alt`** (пустой `alt` только для декора).
-- Иконки-кнопки — **`aria-label`** или visually hidden text.
-- Динамические обновления — `aria-live` для критичных status/error (умеренно).
+- Images — **`alt`** (empty `alt` only for decoration).
+- Icon buttons — **`aria-label`** or visually hidden text.
+- Dynamic updates — `aria-live` for critical status/error (use sparingly).
 
-## Проверка
+## Verification
 
-- При сомнении — devtools a11y tree или `accessibility-reviewer` в pipeline для UI-heavy фич.
+- When unsure — devtools a11y tree or `accessibility-reviewer` in the pipeline for UI-heavy features.

package/presets/claude/next/rules/ui-and-accessibility/react-ui.md

@@ -5,91 +5,91 @@ paths:
 impact: HIGH
 ---
 
-# Общие правила компонентов
+# General component rules
 
-- Использовать **функциональные компоненты** с хуками, без классов.
-- Компонент должен:
-  - быть максимально «тонким» по бизнес‑логике;
-  - делегировать состояние в store/хуки, если оно нужно в нескольких местах;
-  - опираться на **общие UI‑примитивы дизайна проекта** (пакеты или локальная библиотека компонентов), если они есть.
-- Перед новым кастомным контролом — поискать готовый или близкий компонент в репозитории / пакетах UI проекта и переиспользовать или расширить его.
-- Для повторяемой логики создавать `useSomething`‑хуки рядом или в `src/ui/hooks/**`.
-- При обращении к store, API, общим хелперам и утилитам компоненты и хуки должны использовать только их **public API** (например, `@/store`, `@/store/slices/Foo`, `@/lib/utils`), а не импортировать внутренние файлы реализации других модулей.
+- Use **functional components** with hooks, no classes.
+- A component should:
+  - stay as "thin" as possible on business logic;
+  - delegate state to store/hooks when needed in multiple places;
+  - rely on **shared project UI design primitives** (packages or local component library), if present.
+- Before a new custom control — search for an existing or close component in the repository / project UI packages and reuse or extend it.
+- For repeated logic, create `useSomething` hooks nearby or in `src/ui/hooks/**`.
+- When accessing store, API, shared helpers, and utilities, components and hooks must use only their **public API** (for example, `@/store`, `@/store/slices/Foo`, `@/lib/utils`), not internal implementation files of other modules.
 
-# Структура файлов
+# File structure
 
-Для страницы/крупного блока:
+For a page/large block:
 
-- `FeatureBlock.tsx` — JSX и композиция.
-- `styles.ts` или соседний модуль стилей — по конвенции репозитория (CSS Modules, CSS-in-JS, и т.д.).
-- `index.ts` — реэкспорт (если нужно наружу).
+- `FeatureBlock.tsx` — JSX and composition.
+- `styles.ts` or adjacent style module — per repository convention (CSS Modules, CSS-in-JS, etc.).
+- `index.ts` — re-export (if needed externally).
 
-## Дочерние компоненты (`./components`)
+## Child components (`./components`)
 
-- Локальные подкомпоненты, используемые только этим блоком, выносятся в **`./components/<ComponentName>/`** относительно папки родительского компонента (не оставлять крупные куски JSX и «внутренние» компоненты в том же файле, что и родитель).
-- У каждого такого подкомпонента — **своя** папка с тем же именем, что и публичное имя компонента:
-  - `ComponentName.tsx` — разметка и композиция;
-  - `styles.ts` — только стили этого подкомпонента (не тянуть `styles` соседних компонентов — см. § Стили ниже);
-  - при необходимости — `ComponentName.data.ts`, `ComponentName.utils.ts`, `ComponentName.hooks.ts` по тем же правилам префикса, что и у родителя;
-  - опционально `index.ts` с реэкспортом.
-- Родитель импортирует подкомпонент из `./components/...`, а не держит его реализацию inline.
+- Local subcomponents used only by this block go in **`./components/<ComponentName>/`** relative to the parent component folder (do not leave large JSX chunks and "internal" components in the same file as the parent).
+- Each subcomponent has **its own** folder with the same name as the public component:
+  - `ComponentName.tsx` — markup and composition;
+  - `styles.ts` — styles for this subcomponent only (do not import `styles` from sibling components — see Styles below);
+  - when needed — `ComponentName.data.ts`, `ComponentName.utils.ts`, `ComponentName.hooks.ts` with the same prefix rules as the parent;
+  - optional `index.ts` re-export.
+- The parent imports subcomponents from `./components/...`, not inline implementations.
 
-Для переиспользуемого компонента:
+For a reusable component:
 
-- Папка с именем компонента:
+- Folder named after the component:
   - `ComponentName.tsx`
-  - файлы стилей по принятой схеме;
-  - опционально: `types.ts`, `ComponentName.hooks.ts` (см. ниже про префикс).
+  - style files per project scheme;
+  - optional: `types.ts`, `ComponentName.hooks.ts` (see prefix rules below).
 
-## Вспомогательные модули рядом с компонентом (именование)
+## Adjacent helper modules (naming)
 
-**Префикс имени файла = публичное имя компонента** (как у `ComponentName.tsx` в этой папке), в **PascalCase**. Не вводить отдельные «говорящие» имена файлов по смыслу содержимого (`analysisPreparationIconMap.ts`, `buildAnalysisIdToNameMap.ts` и т.п.) — так теряется связь с компонентом и плодятся одноразовые названия.
+**File name prefix = public component name** (as in `ComponentName.tsx` in that folder), in **PascalCase**. Do not introduce separate "descriptive" file names by content meaning (`analysisPreparationIconMap.ts`, `buildAnalysisIdToNameMap.ts`, etc.) — that breaks the link to the component and creates one-off names.
 
-**Суффикс по роли:**
+**Role suffix:**
 
-| Суффикс | Назначение | Примеры содержимого |
-|--------|------------|---------------------|
-| `ComponentName.data.ts` | Статические данные и конфигурация для UI | мапы `id → иконка/лейбл`, константы списков, таблицы соответствий для отображения |
-| `ComponentName.utils.ts` | Чистые функции без React | форматирование, предобработка пропсов/данных для рендера, `build…`/`map…`‑хелперы |
-| `ComponentName.hooks.ts` | Хуки, используемые только этим блоком | локальные `use…` (если не вынесены в `src/ui/hooks/**`) |
+| Suffix | Purpose | Content examples |
+|--------|---------|------------------|
+| `ComponentName.data.ts` | Static data and UI configuration | `id → icon/label` maps, list constants, display lookup tables |
+| `ComponentName.utils.ts` | Pure non-React functions | formatting, prop/data preprocessing for render, `build…`/`map…` helpers |
+| `ComponentName.hooks.ts` | Hooks used only by this block | local `use…` (if not moved to `src/ui/hooks/**`) |
 
-- Несколько констант/мапов или несколько функций — **по-прежнему один** `.data.ts` и один `.utils.ts`, не дробить по «темам» отдельными файлами без веской причины (размер, разные зоны ответственности на уровне подкомпонентов).
-- Если логика принадлежит **подкомпоненту** в подпапке (`components/Child/Child.tsx`), те же правила применяются к **`Child.data.ts`**, **`Child.utils.ts`** относительно этого подкомпонента.
-- Тесты для утилит и данных — рядом в `__tests__/` или с суффиксом `.test.ts`, согласно `testing/tests-unit.md`, с тем же префиксом (`RequestForAnalysisRecommendations.utils.test.ts` и т.д.).
+- Multiple constants/maps or multiple functions — still **one** `.data.ts` and one `.utils.ts`; do not split by "topic" into separate files without good reason (size, different responsibility at subcomponent level).
+- If logic belongs to a **subcomponent** in a subfolder (`components/Child/Child.tsx`), the same rules apply to **`Child.data.ts`**, **`Child.utils.ts`** for that subcomponent.
+- Tests for utilities and data — nearby in `__tests__/` or with `.test.ts` suffix per `testing/tests-unit.md`, same prefix (`RequestForAnalysisRecommendations.utils.test.ts`, etc.).
 
-# Стили и дизайн‑токены
+# Styles and design tokens
 
-- **Корневой** styled в соседнем `styles` — экспорт **`Root`**; в JSX: `<s.Root>` при `import * as s from './styles'`. Вложенные — `Title`, `List` и т.д. Не `Container`/`Wrapper` для единственной обёртки.
-- **Запрещено** импортировать `styles` другого компонента (`../Other/styles`, `../../styles`). Разрешено: `./styles`, общие примитивы из `@/ui/components/...` или пакетов дизайн-системы.
-- Порядок CSS / `styled` — Stylelint idiomatic-order: `ui-and-accessibility/css-property-order.md` (грузится на `styles.ts` / `.css`).
-- Для визуала использовать **тот стек стилей и токенов, который уже в проекте** (переменные, тема, общие классы, дизайн‑пакет).
-- Избегать:
-  - inline‑стилей, кроме простых случаев;
-  - дублирования оформления, уже закрытого общими примитивами;
-  - «магических» литералов (`#xxxxxx`, произвольные `17px` / `23px`), если в проекте есть токены или масштаб.
-- Если подходящего токена нет — локальный примитив **в одном месте** с последующим выравниванием под систему дизайна при возможности.
+- **Root** styled export in adjacent `styles` — **`Root`**; in JSX: `<s.Root>` with `import * as s from './styles'`. Nested — `Title`, `List`, etc. Not `Container`/`Wrapper` for a single wrapper.
+- **Forbidden** to import another component's `styles` (`../Other/styles`, `../../styles`). Allowed: `./styles`, shared primitives from `@/ui/components/...` or design-system packages.
+- CSS / `styled` order — Stylelint idiomatic-order: `ui-and-accessibility/css-property-order.md` (loads on `styles.ts` / `.css`).
+- For visuals use **the style stack and tokens already in the project** (variables, theme, shared classes, design package).
+- Avoid:
+  - inline styles except simple cases;
+  - duplicating styling already covered by shared primitives;
+  - "magic" literals (`#xxxxxx`, arbitrary `17px` / `23px`) when the project has tokens or scale.
+- If no suitable token exists — a local primitive **in one place**, aligned with the design system when possible.
 
-# Пропсы и типизация
+# Props and typing
 
-- **Не передавать пропы в компоненты через spread** (`<Foo {...x} />`). Только явные атрибуты; подробности — `ui-and-accessibility/no-props-spread.md` (в `app/src/ui` это дополнительно ловит ESLint).
-- Описывать пропсы через `type Props = { ... }` или `interface Props { ... }`.
-- Не использовать `any`; при необходимости — обобщения (`<T>`), `unknown`, type guards.
-- Для доменных сущностей использовать типы из `@/types` (и enum из `@/types/enums`), а не описывать их заново (`architecture/public-imports.md`).
+- **Do not pass props via spread** (`<Foo {...x} />`). Only explicit attributes; details — `ui-and-accessibility/no-props-spread.md` (in `app/src/ui` ESLint catches this too).
+- Describe props with `type Props = { ... }` or `interface Props { ... }`.
+- Do not use `any`; when needed — generics (`<T>`), `unknown`, type guards.
+- For domain entities use types from `@/types` (and enums from `@/types/enums`), not redefined locally (`architecture/public-imports.md`).
 
-# Логика и side effects
+# Logic and side effects
 
-- Side effects и асинхронщина — по возможности в store (thunk’и, middleware) или в отдельные хуки.
-- Компоненты не должны:
-  - напрямую знать детали API (URL, структура DTO);
-  - заниматься маппингом «сырых» DTO — только доменные типы;
-  - содержать нетривиальные вычисления и преобразования данных (булевы флаги, сложная склейка строк, агрегаты и т.п.). Данные для отображения должны быть подготовлены на этапах маппинга/подготовки (API → доменная модель → store).
+- Side effects and async — when possible in store (thunks, middleware) or dedicated hooks.
+- Components must not:
+  - know API details directly (URL, DTO shape);
+  - map "raw" DTOs — only domain types;
+  - contain non-trivial computations and data transforms (boolean flags, complex string concatenation, aggregates, etc.). Display data should be prepared at mapping/preparation stages (API → domain model → store).
 
-# Тестирование UI
+# UI testing
 
-- Для нетривиальных компонентов добавлять тесты:
-  - **Testing Library** для React, как принято в проекте;
-  - проверять поведение и бизнес‑правила, а не конкретные CSS‑классы.
-- В тестах ориентироваться на текст, роли и aria‑атрибуты.
+- For non-trivial components add tests:
+  - **Testing Library** for React as adopted in the project;
+  - verify behavior and business rules, not specific CSS classes.
+- In tests prefer text, roles, and aria attributes.
 ## Incorrect
 
 ```tsx

package/presets/claude/next/skills/README.md

@@ -1,9 +1,9 @@
 # `.claude/skills` (preset next)
 
-[Skills](https://code.claude.com/docs/en/skills) в Claude Code — сценарии, которые подгружаются по необходимости, а не в каждой сессии целиком. Они синхронизированы по смыслу с `.cursor/skills` из Cursor-пресета.
+[Skills](https://code.claude.com/docs/en/skills) in Claude Code are scenarios loaded on demand, not in every session in full. They match the intent of `.cursor/skills` from the Cursor preset.
 
-| Skill | Когда использовать |
-|-------|--------------------|
+| Skill | When to use |
+|-------|-------------|
 | `feature-delivery` | End-to-end feature work across types, API, store, UI, tests |
 | `code-review` | MR/diff review using project architecture and test standards |
 | `debug-investigation` | Reproducing and fixing bugs with root-cause evidence |
@@ -14,4 +14,4 @@
 | `write-adr` | Author an Architecture Decision Record (context / decision / consequences) |
 | `react-performance` | Implementer checklist: bundle, RSC/client, memo, waterfalls, CWV (not a perf audit agent) |
 
-Папка копируется в `.claude/skills/` при `ai-rules init claude --preset next`, если существует.
+The folder is copied to `.claude/skills/` on `ai-rules init claude --preset next` when it exists.

package/presets/claude/next/skills/feature-delivery/SKILL.md

@@ -8,7 +8,7 @@ description: Delivers Next.js frontend features end-to-end across domain types,
 1. Read task brief, acceptance criteria, and decomposition if present.
 2. Read **`rules/architecture/feature-delivery-workflow.md`** and **`rules/architecture/reference-features.md`** — follow layer order and mirror closest reference feature.
 3. Add or update focused tests for changed behavior.
-4. Validation from `app/`: **invoke** **`rules/tooling-and-review/post-change-lint.md`** after code edits (requestable, not session-start — but mandatory when code changed). Pipeline: scoped lint OK if next step is `build-verifier`.
+4. Validation from `app/`: **invoke** **`rules/tooling-and-review/post-change-lint.md`** after code edits (requestable, not session-start — but **must** when code changed). Pipeline: scoped lint OK if next step is `build-verifier`.
 
 ## Scope discipline
 

package/presets/claude/next/team/README.md

@@ -1,6 +1,6 @@
 # Agent team artifacts
 
-Каталог артефактов пайплайна «команда агентов» Claude.
+Artifact directory for the Claude “agent team” pipeline.
 
 ## Layout
 
@@ -97,7 +97,7 @@ Prefer **`executing`** for pipeline mode. Legacy: `analysis`, `development`, `re
 ## Workflow entry
 
 ```bash
-/task <описание задачи>
+/task <task description>
 /task-continue <slug>
 /technical-retro <slug>
 ```

package/presets/claude/nuxt/CLAUDE.md

@@ -0,0 +1,39 @@
+# Nuxt stack — project instructions
+
+Short entry point for Claude Code. Detailed rules — modular files under `rules/` (topic subfolders).
+
+**Repo-root agents:** see [`AGENTS.md`](../../AGENTS.md) at the project root (cross-tool setup, commands, security, living conventions pointers).
+
+See @rules/README.md for the full catalog and loading strategy.
+
+## Conventions
+
+- **One topic per file**; for large areas — subfolders under `rules/<topic>/`.
+- **Session-start rules** (no `paths:`) — exactly **three**: `nuxt-app-core`, `package-manager`, `code-quality`.
+- **Domain-specific rules** — YAML frontmatter `paths:` (loaded when matching files); `post-change-lint` — requestable (**required after code edits**); orchestrator and code-review — on-demand.
+- Slash commands — in `commands/`; scenarios — in `skills/`; subagents — in `agents/`.
+
+## Quick start
+
+| Task | Where to look |
+|------|----------------|
+| Any new work task | `commands/task.md` + `rules/tooling-and-review/agent-team-orchestrator.md` |
+| New end-to-end feature | skill `feature-delivery` + `rules/architecture/feature-delivery-workflow.md` |
+| Reference features | `rules/architecture/reference-features.md` (fill TBD in the repo) |
+| Stack and layers | `rules/stack/nuxt-app-core.md` |
+| Nuxt routing | `rules/stack/nuxt-pages-routing.md` |
+| A11y when coding UI | `rules/ui-and-accessibility/vue-a11y-coding.md` |
+| After code edits | `rules/tooling-and-review/post-change-lint.md` (**requestable**, required after edits) |
+| Validation before review | agent `build-verifier` |
+| Code review MR | skill `code-review` + `rules/tooling-and-review/code-review-mr.md` |
+| Security (auth/forms/env) | `rules/tooling-and-review/security-nuxt.md` + agent `security-reviewer` |
+| How X works | agent `codebase-analyzer` (explain-as-is; no `/task`) |
+| Technical retro | `commands/technical-retro.md` + skill `technical-retro` |
+
+## Install
+
+```bash
+npx @bonesofspring/ai-rules init claude --preset nuxt
+```
+
+Copies `CLAUDE.md`, `rules/**`, `commands/**`, `agents/**`, `hooks/**`, `team/**`, `MCP.md` into `.claude/`, plus `mcp.json` → **`.mcp.json`** and `REPO_AGENTS.md` → root **`AGENTS.md`**. Skills: `write-adr`, `vue-performance` (on-demand).

package/presets/claude/nuxt/MCP.md

@@ -0,0 +1,16 @@
+# MCP (preset `nuxt`, Claude Code)
+
+Copied to the **project root** as `.mcp.json` on `ai-rules init claude --preset nuxt` (not under `.claude/` — that is how Claude Code project scope works).
+
+## Servers
+
+| Name | Package | Why |
+|------|---------|-----|
+| `context7` | `@upstash/context7-mcp` | Up-to-date Vue/Nuxt/TS docs |
+| `playwright-test` | `@playwright/mcp` | Browser MCP; server name matches `mcp__playwright-test__*` in agents |
+| `chrome-devtools` | `chrome-devtools-mcp` | Live DOM/network/performance |
+| `figma` | remote `https://mcp.figma.com/mcp` | Design context → code; OAuth on first connect |
+
+Do not commit secrets. Optional: `CONTEXT7_API_KEY`. Figma — OAuth (do not write the token into the file). After clone/init Claude Code will ask to approve project MCP (`/mcp`).
+
+For the full Playwright Test Agents loop (`planner_*` / `generator_*` / `test_*`) additionally: `npx playwright init-agents --loop=claude` in the app with `@playwright/test`.

package/presets/claude/nuxt/README.md

@@ -0,0 +1,39 @@
+# Preset `nuxt` (Claude Code)
+
+Layout differs from the Cursor preset: here the typical **Claude Code project layout** under `.claude/` is mirrored, not a flat `.mdc` list in `rules/`.
+
+| In the preset | Where `ai-rules init claude --preset nuxt` copies |
+|---------------|---------------------------------------------------|
+| `CLAUDE.md` | `.claude/CLAUDE.md` (entry point, loaded at session start) |
+| `rules/**` | `.claude/rules/**` (recursive: topic subfolders; see [docs](https://code.claude.com/docs/en/memory#organize-rules-with-clauderules)) |
+| `commands/**` | `.claude/commands/**` |
+| `skills/**` | `.claude/skills/**` (if present) |
+| `agents/**` | `.claude/agents/**` (if present) |
+| `hooks/**` | `.claude/hooks/**` (if present) |
+| `team/**` | `.claude/team/**` (agent-team artifact template) |
+| `mcp.json` | **`.mcp.json`** at project root (Claude project MCP) |
+| `MCP.md` | `.claude/MCP.md` |
+
+Rule files are ordinary Markdown with optional YAML frontmatter (`paths:` for path scope), not Cursor `.mdc`.
+
+## Preset taxonomy & contributing
+
+- **Layers:** Core → Stack → Platform — [`../../_shared/README.md`](../../_shared/README.md)
+- **Contribution guide:** [`../../docs/PRESET-CONTRIBUTION.md`](../../docs/PRESET-CONTRIBUTION.md)
+- **Cursor SoT:** `presets/cursor/nuxt/` — this preset is the derived twin; edit Cursor first, same PR
+- **Cursor→Claude map + core table:** [`rules/README.md`](./rules/README.md)
+- **Author meta:** `tooling-and-review/preset-*.md` (`paths:` on `packages/ai-rules/presets/**` only)
+
+## Agent team workflow
+
+The Cursor and Claude presets share the same workflow intent:
+
+- `/task <desc>` → `task-router` → `pipeline.json`;
+- `/task-continue <slug>` → continue after a human gate;
+- `.claude/agents/*.md` → **22** roles: planning (router, analyst, architect, migration, api-contract), analysis (`codebase-analyzer`), implementation (debugger, ci-investigator, developer), review (code, a11y, security, perf), testing (QA, unit trio, playwright trio), docs (tech-writer), build (build-verifier);
+- `.claude/team/tasks/<slug>/` → handoff artifacts (`brief.md`, `decomposition.md`, `review.md`, `migration-plan.md`, `ci-report.md`, `status.json`, …).
+
+## Cross-tool root AGENTS
+
+`REPO_AGENTS.md` → project-root `AGENTS.md` on init. Living conventions: `team/conventions.md`. Skill `write-adr` on-demand.
+Nuxt also ships `vue-performance` skill and Incorrect/Correct samples on golden domain rules.

package/presets/claude/nuxt/REPO_AGENTS.md

@@ -0,0 +1,49 @@
+# Nuxt 3 — agent instructions
+
+Cross-tool repo-root guide. Tool-specific maps stay under `.cursor/AGENTS.md` and `.claude/CLAUDE.md`.
+
+## Cross-tool setup
+
+- Treat this file as the **shared** entry for any agent (Cursor, Claude Code, or other).
+- Tool maps (agent-team tables, slash commands) live in `.cursor/AGENTS.md` / `.claude/CLAUDE.md` — use them when that tool is installed.
+- Install:
+
+```bash
+npx @bonesofspring/ai-rules init cursor --preset nuxt
+npx @bonesofspring/ai-rules init claude --preset nuxt
+```
+
+`init` overwrites this file from the preset (`REPO_AGENTS.md` → `AGENTS.md`). Living gotchas belong in `team/conventions.md`, not here.
+
+## Commands (test / lint / build)
+
+Working directory for package scripts: **repository root** (directory with `nuxt.config.*`). Detect the package manager from lockfile / `packageManager` (`package-manager` rule).
+
+| Gate | Typical command |
+|------|-----------------|
+| Lint JS | `yarn lint:js` (or project equivalent) from repo root |
+| Lint CSS | `yarn lint:css` from repo root |
+| Typecheck | `yarn typecheck` (`nuxt typecheck`) from repo root |
+| Unit tests | project unit script (often Vitest) at repo root |
+| Build | project `build` / `nuxt build` at repo root |
+
+After code edits: invoke **`post-change-lint`** (requestable). Full gate: agent `build-verifier`.
+
+## Security basics
+
+- Do not commit secrets (`.env`, tokens, credentials).
+- Review destructive git (`reset --hard`, force-push) before running; respect shell hooks.
+- Do not weaken CI or skip hooks unless the user explicitly asks.
+
+## Tool entry points
+
+| Tool | Map |
+|------|-----|
+| Cursor | `.cursor/AGENTS.md` (optional if Cursor not installed) |
+| Claude Code | `.claude/CLAUDE.md` (optional if Claude not installed) |
+
+Rules: `.cursor/rules/` or `.claude/rules/`. Skills: `.cursor/skills/` or `.claude/skills/`.
+
+## Living conventions
+
+Gotchas, local patterns, and team decisions: **`.cursor/team/conventions.md`** and/or **`.claude/team/conventions.md`** (fill after init; not overwritten on every dogfood sync when already present).