{"owner":"rommapp","repo":"romm","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md","CLAUDE.md"],"skills":{"AGENTS.md":"# Repository Instructions\n\nRead and follow [CLAUDE.md](CLAUDE.md) for all repository instructions.\n","CLAUDE.md":"# RomM - Repository Guide for Contributors & Agents\n\nRomM is a self-hosted ROM manager and player: scan a game library off disk, enrich it with metadata from 10+ providers, browse it in a web UI, and play in the browser.\n\n---\n\n## The stack at a glance\n\n|           | Backend                                     | Frontend                                  |\n| --------- | ------------------------------------------- | ----------------------------------------- |\n| Path      | `backend/`                                  | `frontend/`                               |\n| Language  | Python 3.13+                                | TypeScript 5.7 (Vue 3)                    |\n| Framework | FastAPI, SQLAlchemy 2.0, Alembic            | Vue 3 + Vite, Vuetify, Pinia, Vue Router  |\n| Infra     | Redis + RQ (jobs/cache/sessions), Socket.IO | vue-i18n, Socket.IO client                |\n| DB        | MariaDB (default), MySQL, PostgreSQL        | -                                         |\n| Tooling   | `uv`, pytest, Trunk (ruff/black/isort/mypy) | `npm`, vue-tsc, ESLint, Vitest, Storybook |\n\nThe frontend talks to the backend over `/api/*` (REST) and `/ws` (Socket.IO). TypeScript types are **generated** from the backend's OpenAPI schema into `frontend/src/__generated__/` - the backend is the single source of truth for API shapes.\n\n### Deep-dive references\n\n- **`docs/BACKEND_ARCHITECTURE.md`** - directory map, ER diagram, every endpoint, auth/scopes, tasks.\n- **`docs/FRONTEND_ARCHITECTURE.md`** - routing, stores, services, theming, build tooling.\n- **`DEVELOPER_SETUP.md`** - Docker and manual local setup (mock library, `.env`, services).\n- **`CONTRIBUTING.md`** - contribution flow, **AI-assistance disclosure**, translations.\n\n---\n\n## The frontend has two UIs - know which you're in\n\n- **v1 is frozen.** Everything under `frontend/src/views/`, `src/components/`, `src/console/`, `src/layouts/` is legacy and will be deleted wholesale in a final wave. **Do not refactor v1.** Only touch it for a critical bug, and when a v2 fork exists, mark the v1 export `@deprecated`.\n- **v2 is the active rewrite** under `frontend/src/v2/`, gated by `user.ui_settings.uiVersion`. It has its own design system (tokens), primitive library (`R*` components in `src/v2/lib/`), universal input (mouse/touch/keyboard/gamepad), and responsive system. New frontend work goes in v2.\n\nv2 has a detailed constitution, split across focused skills (below). **Read the relevant skill before editing v2 code.**\n\n---\n\n## Skills - load the focused guide for your task\n\nThese live in `.claude/skills/` and carry the detailed rules. Invoke the one that matches what you're doing:\n\n| Skill                    | When                                                                                                                                             |\n| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `frontend-v2-components` | Building/editing any v2 component - tiers (lib/shared/feature), file & SFC conventions, barrels, anti-patterns.                                  |\n| `frontend-v2-theming`    | Colors, tokens, light/dark themes, visual language - and the **zero-hex-literal** policy.                                                        |\n| `frontend-v2-input`      | Interactive components, focus/spatial navigation, gamepad/keyboard, breakpoints & responsive layout.                                             |\n| `frontend-v2-patterns`   | Feature behavior - errors/snackbars, loading, sockets, state persistence, pagination, forms, permissions, destructive confirmations.             |\n| `frontend-i18n`          | Any user-visible string or change under `frontend/src/locales/**`.                                                                               |\n| `backend-development`    | Endpoints, handlers, models, schemas, metadata adapters, tasks, migrations under `backend/`.                                                     |\n| `pre-pr-verification`    | Before committing / opening a PR / declaring done - the checks that keep CI green.                                                               |\n| `security-audit`         | Vetting a diff (release tag range or PR) for anything malicious or a security regression - supply chain, egress, auth/injection, CI, provenance. |\n\n---\n\n## Repo-wide rules\n\n**Disclose AI assistance in the PR.** RomM requires it (see `CONTRIBUTING.md`): state that AI was used and to what extent. This is mandatory and non-negotiable for agent-written contributions.\n**Branch off `master`; open PRs against `master`.** Fork → feature branch → PR. Don't push to `master`.\n**Linting is via [Trunk](https://trunk.io)** (`trunk fmt && trunk check`) — it wraps ruff, black, isort, mypy, ESLint, Prettier, and more, and runs in CI on every PR. **Never commit with `--no-verify`.**\n**The backend owns the API contract.** Changed a response schema or route? Regenerate frontend types (`npm run generate`) and re-typecheck.\n**Tests travel with code.** New logic gets a test; new endpoints get endpoint tests; new v2 primitives get a Storybook story (+ `play()` if interactive).\n**Verify before handoff.** Don't say \"done\" on UI work without testing it in the browser in both themes and all input modalities. See `pre-pr-verification`.\n**English first.** Outside of language files, all code, comments, identifiers, `.md` files, and commit/PR messages are in English.\n**No em-dashes.** Never use em-dashes (—) when writing comments or text. Use commas, parentheses, or separate sentences instead.\n**Keep comments short.** Comments should be concise, and focus on the \"why\" rather than the \"what\" (the code itself is the \"what\"). Avoid long paragraphs; break them into multiple lines or sentences.\n**Don't restate the code.** The code is self-documenting, so skip comments that narrate what a reader can already see (which button sits where, that something is disabled when empty, obvious ordering). Comment only non-obvious \"why\" that the code can't convey on its own.\n**Never commit secrets.** Never commit secrets (API keys, passwords, tokens, etc.) to the repo. Use environment variables or secret management tools instead.\n**Don't explain a change.** Avoid comments that explain why a change was made to the code. Focus instead on the current behaviour of the code and how it works.\n**Python tools live in `backend/tools/`.** Standalone dev/test utilities and scripts (not part of the app runtime) go in `backend/tools/`, not scattered across `backend/`.\n**Link PRs to issues.** In the PR description, use `Fixes #XXXX` for issue/bug fixes and `Closes #XXXX` for feature implementations.\n**Use the PR template.** Base every PR description on `.github/PULL_REQUEST_TEMPLATE.md`.\n\n---\n\n## Quick command reference\n\n**Setup:** see `DEVELOPER_SETUP.md`. Docker path is `cp env.template .env` → `docker compose build` → `docker compose up -d` (app at `http://localhost:3000`).\n\n**Backend** (`cd backend`):\n\n```bash\nuv sync --all-extras --dev          # install\nuv run main.py              # run (migrations auto-apply)\nuv run pytest [path/file]           # test (subset) - or -vv for all\nuv run alembic revision --autogenerate -m \"msg\"   # new migration (then HAND-REVIEW)\nuv run alembic upgrade head         # apply migrations\n```\n\n**Frontend** (`cd frontend`):\n\n```bash\nnpm install                         # install (Node 24)\nnpm run dev                         # dev server :3000\nnpm run typecheck                   # vue-tsc\nnpm run test                        # vitest (+ Storybook play() tests)\nnpm run test:e2e                    # playwright (needs a running app + seeded e2e users)\nnpm run build                       # production build\nnpm run generate                    # regenerate types from backend OpenAPI (backend must be running)\nnpm run build:tokens                # regenerate v2 tokens.css (auto on predev/prebuild)\nnpm run storybook                   # component library on :6006\npython3 src/locales/check_i18n_locales.py   # i18n parity check\npython3 src/locales/check_i18n_sorted.py    # locale keys sorted (--fix to sort)\n```\n\n**Lint (both stacks):** `trunk fmt && trunk check`.\n"},"files":{"AGENTS.md":"# Repository Instructions\n\nRead and follow [CLAUDE.md](CLAUDE.md) for all repository instructions.\n","CLAUDE.md":"# RomM - Repository Guide for Contributors & Agents\n\nRomM is a self-hosted ROM manager and player: scan a game library off disk, enrich it with metadata from 10+ providers, browse it in a web UI, and play in the browser.\n\n---\n\n## The stack at a glance\n\n|           | Backend                                     | Frontend                                  |\n| --------- | ------------------------------------------- | ----------------------------------------- |\n| Path      | `backend/`                                  | `frontend/`                               |\n| Language  | Python 3.13+                                | TypeScript 5.7 (Vue 3)                    |\n| Framework | FastAPI, SQLAlchemy 2.0, Alembic            | Vue 3 + Vite, Vuetify, Pinia, Vue Router  |\n| Infra     | Redis + RQ (jobs/cache/sessions), Socket.IO | vue-i18n, Socket.IO client                |\n| DB        | MariaDB (default), MySQL, PostgreSQL        | -                                         |\n| Tooling   | `uv`, pytest, Trunk (ruff/black/isort/mypy) | `npm`, vue-tsc, ESLint, Vitest, Storybook |\n\nThe frontend talks to the backend over `/api/*` (REST) and `/ws` (Socket.IO). TypeScript types are **generated** from the backend's OpenAPI schema into `frontend/src/__generated__/` - the backend is the single source of truth for API shapes.\n\n### Deep-dive references\n\n- **`docs/BACKEND_ARCHITECTURE.md`** - directory map, ER diagram, every endpoint, auth/scopes, tasks.\n- **`docs/FRONTEND_ARCHITECTURE.md`** - routing, stores, services, theming, build tooling.\n- **`DEVELOPER_SETUP.md`** - Docker and manual local setup (mock library, `.env`, services).\n- **`CONTRIBUTING.md`** - contribution flow, **AI-assistance disclosure**, translations.\n\n---\n\n## The frontend has two UIs - know which you're in\n\n- **v1 is frozen.** Everything under `frontend/src/views/`, `src/components/`, `src/console/`, `src/layouts/` is legacy and will be deleted wholesale in a final wave. **Do not refactor v1.** Only touch it for a critical bug, and when a v2 fork exists, mark the v1 export `@deprecated`.\n- **v2 is the active rewrite** under `frontend/src/v2/`, gated by `user.ui_settings.uiVersion`. It has its own design system (tokens), primitive library (`R*` components in `src/v2/lib/`), universal input (mouse/touch/keyboard/gamepad), and responsive system. New frontend work goes in v2.\n\nv2 has a detailed constitution, split across focused skills (below). **Read the relevant skill before editing v2 code.**\n\n---\n\n## Skills - load the focused guide for your task\n\nThese live in `.claude/skills/` and carry the detailed rules. Invoke the one that matches what you're doing:\n\n| Skill                    | When                                                                                                                                             |\n| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `frontend-v2-components` | Building/editing any v2 component - tiers (lib/shared/feature), file & SFC conventions, barrels, anti-patterns.                                  |\n| `frontend-v2-theming`    | Colors, tokens, light/dark themes, visual language - and the **zero-hex-literal** policy.                                                        |\n| `frontend-v2-input`      | Interactive components, focus/spatial navigation, gamepad/keyboard, breakpoints & responsive layout.                                             |\n| `frontend-v2-patterns`   | Feature behavior - errors/snackbars, loading, sockets, state persistence, pagination, forms, permissions, destructive confirmations.             |\n| `frontend-i18n`          | Any user-visible string or change under `frontend/src/locales/**`.                                                                               |\n| `backend-development`    | Endpoints, handlers, models, schemas, metadata adapters, tasks, migrations under `backend/`.                                                     |\n| `pre-pr-verification`    | Before committing / opening a PR / declaring done - the checks that keep CI green.                                                               |\n| `security-audit`         | Vetting a diff (release tag range or PR) for anything malicious or a security regression - supply chain, egress, auth/injection, CI, provenance. |\n\n---\n\n## Repo-wide rules\n\n**Disclose AI assistance in the PR.** RomM requires it (see `CONTRIBUTING.md`): state that AI was used and to what extent. This is mandatory and non-negotiable for agent-written contributions.\n**Branch off `master`; open PRs against `master`.** Fork → feature branch → PR. Don't push to `master`.\n**Linting is via [Trunk](https://trunk.io)** (`trunk fmt && trunk check`) — it wraps ruff, black, isort, mypy, ESLint, Prettier, and more, and runs in CI on every PR. **Never commit with `--no-verify`.**\n**The backend owns the API contract.** Changed a response schema or route? Regenerate frontend types (`npm run generate`) and re-typecheck.\n**Tests travel with code.** New logic gets a test; new endpoints get endpoint tests; new v2 primitives get a Storybook story (+ `play()` if interactive).\n**Verify before handoff.** Don't say \"done\" on UI work without testing it in the browser in both themes and all input modalities. See `pre-pr-verification`.\n**English first.** Outside of language files, all code, comments, identifiers, `.md` files, and commit/PR messages are in English.\n**No em-dashes.** Never use em-dashes (—) when writing comments or text. Use commas, parentheses, or separate sentences instead.\n**Keep comments short.** Comments should be concise, and focus on the \"why\" rather than the \"what\" (the code itself is the \"what\"). Avoid long paragraphs; break them into multiple lines or sentences.\n**Don't restate the code.** The code is self-documenting, so skip comments that narrate what a reader can already see (which button sits where, that something is disabled when empty, obvious ordering). Comment only non-obvious \"why\" that the code can't convey on its own.\n**Never commit secrets.** Never commit secrets (API keys, passwords, tokens, etc.) to the repo. Use environment variables or secret management tools instead.\n**Don't explain a change.** Avoid comments that explain why a change was made to the code. Focus instead on the current behaviour of the code and how it works.\n**Python tools live in `backend/tools/`.** Standalone dev/test utilities and scripts (not part of the app runtime) go in `backend/tools/`, not scattered across `backend/`.\n**Link PRs to issues.** In the PR description, use `Fixes #XXXX` for issue/bug fixes and `Closes #XXXX` for feature implementations.\n**Use the PR template.** Base every PR description on `.github/PULL_REQUEST_TEMPLATE.md`.\n\n---\n\n## Quick command reference\n\n**Setup:** see `DEVELOPER_SETUP.md`. Docker path is `cp env.template .env` → `docker compose build` → `docker compose up -d` (app at `http://localhost:3000`).\n\n**Backend** (`cd backend`):\n\n```bash\nuv sync --all-extras --dev          # install\nuv run main.py              # run (migrations auto-apply)\nuv run pytest [path/file]           # test (subset) - or -vv for all\nuv run alembic revision --autogenerate -m \"msg\"   # new migration (then HAND-REVIEW)\nuv run alembic upgrade head         # apply migrations\n```\n\n**Frontend** (`cd frontend`):\n\n```bash\nnpm install                         # install (Node 24)\nnpm run dev                         # dev server :3000\nnpm run typecheck                   # vue-tsc\nnpm run test                        # vitest (+ Storybook play() tests)\nnpm run test:e2e                    # playwright (needs a running app + seeded e2e users)\nnpm run build                       # production build\nnpm run generate                    # regenerate types from backend OpenAPI (backend must be running)\nnpm run build:tokens                # regenerate v2 tokens.css (auto on predev/prebuild)\nnpm run storybook                   # component library on :6006\npython3 src/locales/check_i18n_locales.py   # i18n parity check\npython3 src/locales/check_i18n_sorted.py    # locale keys sorted (--fix to sort)\n```\n\n**Lint (both stacks):** `trunk fmt && trunk check`.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Repository Instructions\n\nRead and follow [CLAUDE.md](CLAUDE.md) for all repository instructions.\n","category":"root","tokens":25},{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# RomM - Repository Guide for Contributors & Agents\n\nRomM is a self-hosted ROM manager and player: scan a game library off disk, enrich it with metadata from 10+ providers, browse it in a web UI, and play in the browser.\n\n---\n\n## The stack at a glance\n\n|           | Backend                                     | Frontend                                  |\n| --------- | ------------------------------------------- | ----------------------------------------- |\n| Path      | `backend/`                                  | `frontend/`                               |\n| Language  | Python 3.13+                                | TypeScript 5.7 (Vue 3)                    |\n| Framework | FastAPI, SQLAlchemy 2.0, Alembic            | Vue 3 + Vite, Vuetify, Pinia, Vue Router  |\n| Infra     | Redis + RQ (jobs/cache/sessions), Socket.IO | vue-i18n, Socket.IO client                |\n| DB        | MariaDB (default), MySQL, PostgreSQL        | -                                         |\n| Tooling   | `uv`, pytest, Trunk (ruff/black/isort/mypy) | `npm`, vue-tsc, ESLint, Vitest, Storybook |\n\nThe frontend talks to the backend over `/api/*` (REST) and `/ws` (Socket.IO). TypeScript types are **generated** from the backend's OpenAPI schema into `frontend/src/__generated__/` - the backend is the single source of truth for API shapes.\n\n### Deep-dive references\n\n- **`docs/BACKEND_ARCHITECTURE.md`** - directory map, ER diagram, every endpoint, auth/scopes, tasks.\n- **`docs/FRONTEND_ARCHITECTURE.md`** - routing, stores, services, theming, build tooling.\n- **`DEVELOPER_SETUP.md`** - Docker and manual local setup (mock library, `.env`, services).\n- **`CONTRIBUTING.md`** - contribution flow, **AI-assistance disclosure**, translations.\n\n---\n\n## The frontend has two UIs - know which you're in\n\n- **v1 is frozen.** Everything under `frontend/src/views/`, `src/components/`, `src/console/`, `src/layouts/` is legacy and will be deleted wholesale in a final wave. **Do not refactor v1.** Only touch it for a critical bug, and when a v2 fork exists, mark the v1 export `@deprecated`.\n- **v2 is the active rewrite** under `frontend/src/v2/`, gated by `user.ui_settings.uiVersion`. It has its own design system (tokens), primitive library (`R*` components in `src/v2/lib/`), universal input (mouse/touch/keyboard/gamepad), and responsive system. New frontend work goes in v2.\n\nv2 has a detailed constitution, split across focused skills (below). **Read the relevant skill before editing v2 code.**\n\n---\n\n## Skills - load the focused guide for your task\n\nThese live in `.claude/skills/` and carry the detailed rules. Invoke the one that matches what you're doing:\n\n| Skill                    | When                                                                                                                                             |\n| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `frontend-v2-components` | Building/editing any v2 component - tiers (lib/shared/feature), file & SFC conventions, barrels, anti-patterns.                                  |\n| `frontend-v2-theming`    | Colors, tokens, light/dark themes, visual language - and the **zero-hex-literal** policy.                                                        |\n| `frontend-v2-input`      | Interactive components, focus/spatial navigation, gamepad/keyboard, breakpoints & responsive layout.                                             |\n| `frontend-v2-patterns`   | Feature behavior - errors/snackbars, loading, sockets, state persistence, pagination, forms, permissions, destructive confirmations.             |\n| `frontend-i18n`          | Any user-visible string or change under `frontend/src/locales/**`.                                                                               |\n| `backend-development`    | Endpoints, handlers, models, schemas, metadata adapters, tasks, migrations under `backend/`.                                                     |\n| `pre-pr-verification`    | Before committing / opening a PR / declaring done - the checks that keep CI green.                                                               |\n| `security-audit`         | Vetting a diff (release tag range or PR) for anything malicious or a security regression - supply chain, egress, auth/injection, CI, provenance. |\n\n---\n\n## Repo-wide rules\n\n**Disclose AI assistance in the PR.** RomM requires it (see `CONTRIBUTING.md`): state that AI was used and to what extent. This is mandatory and non-negotiable for agent-written contributions.\n**Branch off `master`; open PRs against `master`.** Fork → feature branch → PR. Don't push to `master`.\n**Linting is via [Trunk](https://trunk.io)** (`trunk fmt && trunk check`) — it wraps ruff, black, isort, mypy, ESLint, Prettier, and more, and runs in CI on every PR. **Never commit with `--no-verify`.**\n**The backend owns the API contract.** Changed a response schema or route? Regenerate frontend types (`npm run generate`) and re-typecheck.\n**Tests travel with code.** New logic gets a test; new endpoints get endpoint tests; new v2 primitives get a Storybook story (+ `play()` if interactive).\n**Verify before handoff.** Don't say \"done\" on UI work without testing it in the browser in both themes and all input modalities. See `pre-pr-verification`.\n**English first.** Outside of language files, all code, comments, identifiers, `.md` files, and commit/PR messages are in English.\n**No em-dashes.** Never use em-dashes (—) when writing comments or text. Use commas, parentheses, or separate sentences instead.\n**Keep comments short.** Comments should be concise, and focus on the \"why\" rather than the \"what\" (the code itself is the \"what\"). Avoid long paragraphs; break them into multiple lines or sentences.\n**Don't restate the code.** The code is self-documenting, so skip comments that narrate what a reader can already see (which button sits where, that something is disabled when empty, obvious ordering). Comment only non-obvious \"why\" that the code can't convey on its own.\n**Never commit secrets.** Never commit secrets (API keys, passwords, tokens, etc.) to the repo. Use environment variables or secret management tools instead.\n**Don't explain a change.** Avoid comments that explain why a change was made to the code. Focus instead on the current behaviour of the code and how it works.\n**Python tools live in `backend/tools/`.** Standalone dev/test utilities and scripts (not part of the app runtime) go in `backend/tools/`, not scattered across `backend/`.\n**Link PRs to issues.** In the PR description, use `Fixes #XXXX` for issue/bug fixes and `Closes #XXXX` for feature implementations.\n**Use the PR template.** Base every PR description on `.github/PULL_REQUEST_TEMPLATE.md`.\n\n---\n\n## Quick command reference\n\n**Setup:** see `DEVELOPER_SETUP.md`. Docker path is `cp env.template .env` → `docker compose build` → `docker compose up -d` (app at `http://localhost:3000`).\n\n**Backend** (`cd backend`):\n\n```bash\nuv sync --all-extras --dev          # install\nuv run main.py              # run (migrations auto-apply)\nuv run pytest [path/file]           # test (subset) - or -vv for all\nuv run alembic revision --autogenerate -m \"msg\"   # new migration (then HAND-REVIEW)\nuv run alembic upgrade head         # apply migrations\n```\n\n**Frontend** (`cd frontend`):\n\n```bash\nnpm install                         # install (Node 24)\nnpm run dev                         # dev server :3000\nnpm run typecheck                   # vue-tsc\nnpm run test                        # vitest (+ Storybook play() tests)\nnpm run test:e2e                    # playwright (needs a running app + seeded e2e users)\nnpm run build                       # production build\nnpm run generate                    # regenerate types from backend OpenAPI (backend must be running)\nnpm run build:tokens                # regenerate v2 tokens.css (auto on predev/prebuild)\nnpm run storybook                   # component library on :6006\npython3 src/locales/check_i18n_locales.py   # i18n parity check\npython3 src/locales/check_i18n_sorted.py    # locale keys sorted (--fix to sort)\n```\n\n**Lint (both stacks):** `trunk fmt && trunk check`.\n","category":"root","tokens":2064}]}