# Repository Guidelines

## Project Structure & Module Organization
- `src/main.ts` bootstraps the Vue app, mounts `App.vue`, and registers Pinia + router.
- `src/App.vue` hosts the layout shell; global theme styles live in `src/assets/main.css`.
- `src/pages` holds route-level views (e.g., `HomePage.vue`), wired in `src/router/index.ts`.
- `src/components` contains shareable UI (`Randomizer.vue`); aim to keep these presentational.
- `src/stores` stores state and side effects (e.g., `randomData.ts` for `/api/randomize` and localStorage prefs); static datasets sit in `src/data`.
- `public` serves static assets as-is; `vite.config.ts` configures aliases (`@` → `src`) and plugins.

## Build, Test, and Development Commands
- `npm run dev` — start Vite dev server with hot reload.
- `npm run build` — type-check via `vue-tsc`, then produce the production bundle.
- `npm run build-only` — production bundle without type-check (useful for quick iteration).
- `npm run preview` — serve the built assets locally to verify production output.
- `npm run type-check` — standalone TS/SFC type validation.

## Coding Style & Naming Conventions
- Vue 3 + TypeScript with `<script setup>`; keep logic typed and colocated with templates/styles.
- Use 2-space indentation, single quotes for strings, and omit semicolons to match existing files.
- Components/pages use PascalCase filenames; route-level views use a `Page` suffix.
- Prefer `@/` alias imports over deep relatives; group imports by library/local.
- Keep styles inside SFC blocks or `src/assets/main.css`; reuse existing CSS variables where possible.

## Testing Guidelines
- No automated tests exist yet; before pushing, run `npm run type-check` and `npm run build` to catch regressions.
- Manual QA: exercise the randomizer flow (toggle skills/aspects, adjust item count, observe loading/error states).
- When adding tests, favor Vitest + Vue Test Utils and mirror component filenames (e.g., `Randomizer.spec.ts`).

## Commit & Pull Request Guidelines
- Git history is minimal; use concise, imperative messages (prefer Conventional Commits such as `feat: add randomizer store`) that describe intent.
- PRs should include: summary of changes, impacted areas (UI/store/API), steps to reproduce/test, and screenshots for UI-facing updates.
- Link to relevant issues, keep PRs small and focused, and call out any API or config assumptions (backend `/api/randomize` endpoint, localStorage usage).

## Environment & API Notes
- The frontend expects an `/api/randomize` POST endpoint; if running locally without the backend, configure a mock or Vite proxy.
- Avoid storing secrets in the repo; prefer runtime env vars and document any required values in the PR description.