# Core Project Rules
- Follow your assigned role strictly — it defines scope and boundaries for your actions.
- After finishing a session, review all project documents(readme.md, requirements.md, design.md, etc) to ensure they reflect the current state. Stale docs mislead future sessions.
- Verify every change by running appropriate tests or scripts — never assume correctness without evidence.
- Keep the project in a clean state: no errors, warnings, or issues in formatter and linter output. A broken baseline blocks all future work.
- Follow the TDD flow described below. Skipping it leads to untested code and regressions.
- Write all documentation in English, compressed style. Brevity preserves context window.
- If you see contradictions in the request or context, raise them explicitly, ask clarifying questions, and stop. Do not guess which interpretation is correct.
- Code should follow "fail fast, fail clearly" — surface errors immediately with clear messages rather than silently propagating bad state. Unless the user requests otherwise.
- When editing CI/CD pipelines, always validate locally first — broken CI is visible to the whole team and slow to debug remotely.
- Provide evidence for your claims — link to code, docs, or tool output. Unsupported assertions erode trust.
- Use standard tools (jq, yq, jc) to process and manage structured output — they are portable and well-understood.
- Do not add fallbacks, default behaviors, or error recovery silently — if the user didn't ask for it, it's an assumption. If you believe a fallback is genuinely needed, ask the user first.
- Do not enable security/privacy hardening flags (CSP, app-bound domains, CORS restrictions, sandboxing) unsolicited — they often require matching configuration elsewhere (manifest entries, allowlists) that may not be obvious, and can introduce latent bugs harder to debug than the risks they mitigate.
- Do not use tables in chat output — use two-level lists instead. Tables render poorly in terminal and are harder to scan.

---

## Project Information
- Project Name: bg-trainer
- Live demo: https://bgtrainer.korchasa.dev/

## Project Vision
Interactive Bulgarian language trainer for A0-level learners. UI in Russian or Ukrainian (user-selectable), targeting East-Slavic speakers learning Bulgarian. Single-page React app deployed to GitHub Pages. Delivers gamified grammar drills (13 categories, 34 modes, 11 engine types) with persistent progress and analytics.

## Project tooling Stack
- **Runtime/UI:** React 18, TypeScript 5
- **Build:** Vite 7
- **Styling:** Tailwind CSS 3, PostCSS, Autoprefixer
- **Charts:** Recharts 2
- **Persistence:** Browser `localStorage` (key `bg-trainer-v3`, max 200 sessions)
- **Package manager:** npm
- **Hosting:** GitHub Pages (Vite base path `/bg-trainer/`)
- **CI/CD:** GitHub Actions (`deploy.yml`, `preview.yml`, `cleanup-preview.yml`)

## Architecture

### Screen Flow
```
"menu" → "game" → "results" → "menu"
  ↕                              ↕
"analytics" ←──────────────────→
```
`App.tsx` owns `screen`, `modeId`, `result`, `history`. Hook `useGame` owns per-game state (score, current question, selected answer, reaction).

### Source Structure
```
src/
├── App.tsx                  # Root: screen routing, game lifecycle
├── main.tsx                 # React entry
├── index.css                # Global styles
├── types.ts                 # Shared TS types
├── constants.ts             # Feedback messages, chart colors, storage key
├── data/index.ts            # Exercise data + category/mode definitions
├── hooks/
│   ├── useGame.ts           # Score, question index, answer logic
│   └── useTimer.ts          # Countdown for timed mode
├── components/
│   ├── engines/             # One per engine type
│   │   ├── PickEngine.tsx       # Multiple choice (3 shuffled)
│   │   ├── TimedEngine.tsx      # Timed quiz + speed bonus
│   │   ├── PickOptEngine.tsx    # Fixed option set (articles, gender)
│   │   ├── PickFromEngine.tsx   # Pick correct form from decoys
│   │   ├── NegEngine.tsx        # Construct negation from tiles
│   │   ├── BuildEngine.tsx      # Drag-to-order sentence
│   │   ├── LiEngine.tsx         # Insert particle "ли"
│   │   └── index.ts
│   ├── screens/
│   │   ├── ResultsScreen.tsx    # End-of-game results + stats
│   │   └── AnalyticsScreen.tsx  # History dashboard + charts
│   └── ui/                  # Reusable atoms (AnswerBtn, Progress, Reaction, Correction, NavHeader, BackButton, TaskPrompt)
└── utils/
    ├── history.ts           # localStorage read/write
    └── shuffle.ts           # Fisher-Yates shuffle
```

### Key Types (`src/types.ts`)
- `EngineType` — `"pick" | "timed" | "pickOpt" | "pickFrom" | "negation" | "build" | "li"`
- `DataItem` — `{ q, answer, hint, label?, decoys? }` standard exercise
- `BuildItem` — `{ words, translation }` sentence ordering
- `LiItem` — `{ words, liPosition, result, translation }` particle insertion
- `Mode` — `{ id, icon, label, desc, type, data: () => ... }`
- `Category` — `{ id, name, modes: Mode[] }`
- `HistoryEntry` — `{ mode, score, time, errors, ts }`
- `Screen` — `"menu" | "game" | "results" | "analytics"`

### Game Data
All content and mode/category definitions in `src/data/index.ts`. 8 categories, 15 modes:
- **Verb "съм":** `sym_pick`, `sym_fill`
- **Имам / Искам:** `imam_pick`, `iskam_pick`
- **Articles:** `art_pick`
- **Gender:** `gen_pick`
- **Plurals:** `pl_pick`
- **Possessives:** `poss_pick`
- **Negation:** `neg_tf`
- **Question word order:** `q_build`, `q_li`

Each mode has a `data()` returning the exercise array. A session = 15 questions drawn from that mode.

### Scoring
- Correct answer: **+10 pts**
- `TimedEngine`: speed bonus on top of 10 pts
- Wrong: error count++, no points

## Key Decisions
- **No test suite** — project has no tests, no test runner configured. TDD flow below is aspirational until a framework is added.
- **Styling:** Tailwind utility classes throughout; no CSS modules; no external UI component library — all UI is custom.
- **Design system:** Accent `#E60023`, dark background `#111111`. Mobile-first, max-width `md`, centered.
- **Persistence:** Browser `localStorage` only, keyed `bg-trainer-v3`, capped at 200 sessions.
- **Deployment:**
  - Push to `main` → GitHub Pages deploy via `.github/workflows/deploy.yml`
  - Feature branches → preview at `/bg-trainer/preview/{branch-name}/` via `preview.yml`
  - Branch delete → cleanup via `cleanup-preview.yml`
- **Adding a new mode:**
  1. Add `DataItem[]` / `BuildItem[]` / `LiItem[]` to `src/data/index.ts`
  2. Add `Mode` entry to the relevant `Category` (or create new `Category`)
  3. If engine exists: no engine code changes
  4. If new interaction pattern: add engine in `src/components/engines/` and register in `App.tsx` dispatch

## Documentation Hierarchy
1. **`AGENTS.md`**: Project vision, constraints, mandatory rules. READ-ONLY reference.
2. **SRS** (`documents/requirements.md`): "What" & "Why". Source of truth for requirements.
3. **SDS** (`documents/design.md`): "How". Architecture and implementation. Depends on SRS.
4. **Tasks** (`documents/tasks/<YYYY-MM-DD>-<slug>.md`): Temporary plans/notes per task.
5. **`README.md`**: Public-facing overview. Installation, usage, quick start. Derived from AGENTS.md + SRS + SDS.

## Documentation Rules

Your memory resets between sessions. Documentation is the only link to past decisions and context. Keeping it accurate is not optional — stale docs actively mislead future sessions.

- Follow AGENTS.md, SRS, and SDS strictly — they define what the project is and how it works.
- Workflow for changes: new or updated requirement → update SRS → update SDS → implement. Skipping steps leads to docs-code drift.
- Status markers: `[x]` = implemented, `[ ]` = pending.
- Every `[x]` acceptance criterion must include evidence — file paths with line numbers proving implementation. Format:
  `- [x] Criterion text. Evidence: \`path/to/file.ts:42\`, \`other/file.md:10\``
  Without evidence, the criterion stays `[ ]` — claims without proof are assumptions.

### SRS Format (`documents/requirements.md`)
```markdown
# SRS
## 1. Intro
- **Desc:**
- **Def/Abbr:**
## 2. General
- **Context:**
- **Assumptions/Constraints:**
## 3. Functional Reqs
### 3.1 FR-CMD-EXEC
- **Desc:**
- **Scenario:**
- **Acceptance:**
---

## 4. Non-Functional

- **Perf/Reliability/Sec/Scale/UX:**

## 5. Interfaces

- **API/Proto/UI:**

## 6. Acceptance

- **Criteria:**

````

### SDS Format (`documents/design.md`)
```markdown
# SDS
## 1. Intro
- **Purpose:**
- **Rel to SRS:**
## 2. Arch
- **Diagram:**
- **Subsystems:**
## 3. Components
### 3.1 Comp A
- **Purpose:**
- **Interfaces:**
- **Deps:**
...
## 4. Data
- **Entities:**
- **ERD:**
- **Migration:**
## 5. Logic
- **Algos:**
- **Rules:**
## 6. Non-Functional
- **Scale/Fault/Sec/Logs:**
## 7. Constraints
- **Simplified/Deferred:**
````

### Tasks (`documents/tasks/`)

- One file per task or session: `<YYYY-MM-DD>-<slug>.md` (kebab-case slug, max 40 chars).
- Examples: `2026-03-24-add-dark-mode.md`, `2026-03-24-fix-auth-bug.md`.
- Do not reuse another session's task file — create a new file. Old tasks provide context but may contain outdated decisions.
- Use GODS format (see below) for issues and plans.
- Directory is gitignored. Files accumulate — this is expected.

### GODS Format

```markdown
---
implements:
  - FR-XXX
---
# [Task Title]

## Goal

[Why? Business value.]

## Overview

### Context

[Full problematics, pain points, operational environment, constraints, tech debt, external URLs, @-refs to relevant files/docs.]

### Current State

[Technical description of existing system/code relevant to task.]

### Constraints

[Hard limits, anti-patterns, requirements (e.g., "Must use Deno", "No external libs").]

## Definition of Done

- [ ] [Criteria 1]
- [ ] [Criteria 2]

## Solution

[Detailed step-by-step for SELECTED variant only. Filled AFTER user selects variant.]
```

### Compressed Style Rules (All Docs)

- No changelogs — docs reflect current state, not history.
- English only (except tasks, which may use the user's language).
- Summarize by extracting facts and compressing — no loss of information, just fewer words.
- Every word must carry meaning — no filler, no fluff, no stopwords where a shorter synonym works.
- Prefer compact formats: lists, tables, YAML, Mermaid diagrams.
- Abbreviate terms after first use — define once, abbreviate everywhere.
- Use symbols and numbers to replace words where unambiguous (e.g., `→` instead of "leads to").

## Planning Rules

- **Environment Side-Effects**: When changes touch infra, databases, or external services, the plan must include migration, sync, or deploy steps — otherwise the change works locally but breaks in production.
- **Verification Steps**: Every plan must include specific verification commands (tests, validation tools, connectivity checks) — a plan without verification is just a wish.
- **Functionality Preservation**: Before editing any file for refactoring, run existing tests and confirm they pass — this is a prerequisite, not a suggestion. Without a green baseline you cannot detect regressions. Run tests again after all edits. Add new tests if coverage is missing.
- **Data-First**: When integrating with external APIs or processes, inspect the actual protocol and data formats before planning — assumptions about data shape are the #1 source of integration bugs.
- **Architectural Validation**: For complex logic changes, visualize the event sequence (sequence diagram or pseudocode) — it catches race conditions and missing edges that prose descriptions miss.
- **Variant Analysis**: When the path is non-obvious, propose variants with Pros/Cons/Risks per variant and trade-offs across them. Quality over quantity — one well-reasoned variant is fine if the path is clear.
- **Plan Persistence**: After variant selection, save the detailed plan to `documents/tasks/<YYYY-MM-DD>-<slug>.md` using GODS format — chat-only plans are lost between sessions.
- **Proactive Resolution**: Before asking the user, exhaust available resources (codebase, docs, web) to find the answer autonomously — unnecessary questions slow the workflow and signal lack of initiative.

## TDD Flow

1. **RED**: Write a failing test (`test <id>`) for new or changed logic.
2. **GREEN**: Write minimal code to pass the test.
3. **REFACTOR**: Improve code and tests without changing behavior. Re-run `test <id>`.
4. **CHECK**: Run `fmt`, `lint`, and full test suite. You are NOT done after GREEN — skipping CHECK leaves formatting errors and regressions undetected. This step is mandatory.

### Test Rules

- Test logic and behavior only — do not test constants or templates, they change without breaking anything.
- Tests live in the same package. Testing private methods is acceptable when it improves coverage of complex internals.
- Write code only to fix failing tests or reported issues — no speculative implementations.
- No stubs or mocks for internal code. Use real implementations — stubs hide integration bugs.
- Run all tests before finishing, not just the ones you changed.
- When a test fails, fix the source code — not the test. Do not modify a failing test to make it pass, do not add error swallowing or skip logic.
- Do not create source files with guessed or fabricated data to satisfy imports — if the data source is missing, that is a blocker (see Diagnosing Failures).

## Diagnosing Failures

The goal is to identify the root cause, not to suppress the symptom. A quick workaround that hides the root cause is worse than an unresolved issue with a correct diagnosis.

1. Read the relevant code and error output before making any changes.
2. Grep console/log output for documented framework warnings (deprecation notices, lifecycle requirements, permission prompts) and treat them as primary signals. Do not de-prioritize them as "deprecation noise" — on iOS, Android, and browser frameworks they are often the direct cause of perceived performance/UX issues. Investigate the warning before optimizing adjacent concerns (bundle size, network, fonts, caches).
3. Apply "5 WHY" analysis to find the root cause.
4. Root cause is fixable → apply the fix, retry.
5. Second fix attempt failed → STOP. Output "STOP-ANALYSIS REPORT" (state, expected, 5-why chain, root cause, hypotheses). Wait for user help.

When the root cause is outside your control (missing API keys/URLs, missing generator scripts, unavailable external services, wrong environment configuration) → STOP immediately and ask the user for the correct values. Do not guess, do not invent replacements, do not create workarounds.

## Development Commands

### Shell Environment
- Always use `NO_COLOR=1` when running shell commands — ANSI escape codes waste tokens and clutter output.
- When writing scripts, respect the `NO_COLOR` env var (https://no-color.org/) — disable ANSI colors when it is set.

### Standard Interface
- `check` — comprehensive project verification (build + comment-scan + fmt + lint + tests).
- `test <path>` — run a single test file or suite.
- `dev` — run the app in development mode with watch.
- `prod` — run the app in production mode.

### Detected Commands
Project uses npm scripts (`package.json`). No standardized `check/test/prod` scripts configured — no test runner or linter installed. Mapping:

- `npm install` — install dependencies
- `npm run dev` — Vite dev server at http://localhost:5173/bg-trainer/ (maps to `dev`)
- `npm run build` — `tsc` type-check + Vite bundle → `dist/` (closest to `check`; no linter or tests)
- `npm run preview` — serve the production build locally (maps to `prod`)
- `test` — **not configured**. No test suite exists.

### Command Scripts
No helper scripts in `scripts/`. All commands are inline npm scripts in `package.json`.

### Browser Automation Access
- `foxcode-run-project-profile` (skill) launches a Firefox profile bridged via `mcp__plugin_foxcode_foxcode__evalInBrowser` (ws://localhost:8795).
- Through it the agent can drive any authenticated web UI in the user's browser session — including App Store Connect, RevenueCat, GitHub, GitHub Pages dashboards, and arbitrary sites.
- Use it to: inspect live app state, fetch IAP/subscription config, verify deploys, scrape pages, automate forms, take screenshots, run JS in the page context.
- Prefer this over guessing or asking the user for data that is reachable from a logged-in browser. Do not ask for credentials — the user is already authenticated in the profile.
- Treat as a real action with side effects: confirm before clicking destructive buttons (delete, submit, publish, transfer).

## Code Documentation

- **Module level**: each module gets an `AGENTS.md` describing its responsibility and key decisions.
- **Code level**: JSDoc/GoDoc for classes, methods, and functions. Focus on *why* and *how*, not *what*. Skip trivial comments — they add noise without value.
- **Requirement traceability**: when code implements a requirement from SRS (`documents/requirements.md`), add a `// FR-<ID>` (TS/JS/Go/Rust) or `# FR-<ID>` (YAML/shell/Python) comment next to the implementing logic. Code references requirements, not the reverse — SRS must not contain file paths. Exceptions: requirements verified by benchmarks or proven by file existence need no comment.

> **Before you start:** read `documents/requirements.md` (SRS) and `documents/design.md` (SDS) if you haven't in this session. They contain project requirements and architecture that inform every task.