# Repository instructions

## Local development ports

- Port 5173 is reserved for the user's local Docker container. Never start an agent-run server on port 5173 or stop the container to free that port.
- For local testing, use another available port, for example `npm run dev -- --port 5174 --strictPort`. If it is occupied, choose another port without stopping the existing service.
- Stop agent-started test servers when verification is complete.

## Commit and push shorthand

- When the user says "마무리 해" (or "마무리해"), treat it as authorization to verify the completed task, commit its changes, and push to the configured upstream.
- Otherwise, push only with the user's explicit authorization. Preserve unrelated pending changes and report what was committed and pushed.
- This shorthand does not authorize offline artifacts, version bumps, tags, or separate manual deployments.

## Online-only release policy

- The supported product and release target is the online app, including the GitHub Pages deployment.
- Do not run `npm run build:offline` or `npm run package:offline` during implementation, verification, commits, releases, or deployments.
- Do not create, commit, upload, or publish standalone offline builds, `offline-dist/` output, or offline ZIP artifacts.
- Online/offline feature parity is no longer required. Legacy offline-related source may remain only where the online Pages build still depends on shared adapters.
- Verify repository changes with the relevant tests, `npm run check`, `npm run build`, and `npm run build:pages` when preparing a deployment.
- Do not bump the package version, create version-specific release notes, create tags, or publish GitHub Releases for routine online commits and deployments unless the user explicitly requests them.
- Use `UPDATES.md` as the single user-facing update history and include only changes that affect service users.

## Game DB source policy

- The captured Android game DB is the authoritative master-data source. Use scripts/game-db-source.mjs and the hash-pinned snapshot in data/game-db/current.json. Do not fetch HolodoriDB or substitute third-party data when a table is missing.
- Preserve provenance: SUS charts are separate game assets; live event schedules and bonus rules are absent from this DB. Do not label historical manual event records as DB-derived or invent missing server data.
- Resolve Korean song titles through Music.json titleLangId and LangMusic_Kor.json in the snapshot.
- Keep account credentials, keys, raw memory and recovery files in ignored local inspection directories; only verified master tables and non-secret provenance belong in the source snapshot.

## Collection review before calculator extraction

- A collection request starts with npm run data:sync. Compare every table and string in the selected snapshot with the last successful snapshot in data/game-db/applied.json, including non-calculator systems.
- Read data/game-db/review/latest.json and latest.md. Report semantic changes in Korean, grouped by cards/skills, songs, events, translations and other systems. Include additions, removals, corrections and relevant dates; state unknown meanings explicitly. First import is a snapshot registration, not evidence that every row is newly added content.
- Present the review before npm run data:apply. Then continue authorized collectors without an additional approval. Review-only requests must not extract data.
- Reviewing does not advance the collection baseline. Extraction must use the reviewed snapshot hash; changes require a new review first. Never fall back to older or external sources after validation failure.
- See docs/game-data-source.md for snapshot import and separate game-asset collection.