# CLAUDE.md

Guidance for Claude Code (or any Claude instance) working in this repository.

## What this repo is

The cross-platform **build kit** for Unforged Alchemy 4.0 Player, v147.23. It contains the Player's Python/PySide6 (Qt) source (`app_files/`) plus one PyInstaller build script per target OS. It does not contain a Player game-design doc or the full dev repo — see `app_files/README.md` for what the Player itself does, and `app_files/RULE_SOURCE_AUTHORITY.md` / `app_files/UI_ASSET_POLICY.md` for the rules/art policy that code changes should respect.

## Layout

- `app_files/` — the actual application. `app_files/alchemy/` and `app_files/potion_solver/` (or `app_files/chemical_solver/`, depending on the branch of this kit you're on) hold the core simulation/solver logic; `qt_pages.py`, `qt_frontend.py`, `ui_settings.py`, `integrated_gui_app.py` hold the Qt UI; `run_player_qt.py` is the entry point PyInstaller freezes.
- `build_mac_dmg.sh`, `build_windows_exe.bat`, `build_linux.sh` — one PyInstaller build script per OS. Each is only runnable on its target platform (PyInstaller doesn't cross-compile). They must be kept in sync: the `--add-data` file list is the same set of resources on all three, differing only in path-separator syntax (`:` on macOS/Linux, `;` on Windows) and OS-specific packaging steps (codesign+hdiutil on macOS, tar on Linux, none on Windows).
- `requirements-build.txt` — pinned build-time deps (PySide6, Pillow, PyInstaller), shared by all three scripts.
- `BUILD_KIT_README.md` — human-facing build instructions per platform.
- `site/` — the hostable download page for this kit, in two equivalent forms (`build-kit.astro` for dropping into an existing Astro site, `index.html` for a standalone Cloudflare Pages "Direct Upload" deploy on its own subdomain), plus `site/downloads/` holding a bundled copy of the zip they link to. See `site/README.md` for how the two relate and how to regenerate the bundled zip after changes elsewhere in the repo.

## Working in this repo

- **Do not modify anything under `app_files/` unless the user directly asks for a change to that specific file/behavior.** It's the existing Player codebase, not build-kit scaffolding — treat it as off-limits by default even if a task seems easier by editing it. If a build script or doc issue could plausibly be fixed by touching `app_files/` instead, prefer fixing it in the build kit layer (scripts, requirements, docs) and ask before touching `app_files/`.
- **Don't hand-edit `dist/` or `build/`.** Those are PyInstaller output, regenerated by the build scripts, and are gitignored.
- **If you add a new runtime resource** (a JSON atlas, a new subfolder under `app_files/`, etc.) that the app loads via `runtime_paths.py` / `resource_root()`, add a matching `--add-data` line to **all three** build scripts, not just one — that's the most common way this kit drifts out of sync.
- **Platform-specific UI code** lives behind `sys.platform` checks (see `qt_frontend.py`'s `mac_native` skin) rather than separate per-OS source trees. Keep new platform-conditional behavior additive like this rather than forking files.
- **Skins/themes** are registered in `ui_settings.py` (`SOLVER_SKINS`, `UI_SKINS`, and the `UISettings` preset dict) and consumed in `qt_frontend.py`. Adding a skin means touching both.
- This is a **game tool**, not a game itself — "Chemical," "Potion," "Material," "Distillation," "Synthesis," etc. are domain terms from the app's own alchemy system, not generic naming.
- **`site/index.html` and `site/build-kit.astro` must stay visually and textually identical** — they're the same page in two formats (static HTML for a standalone Cloudflare deploy, Astro for dropping into an existing site). Edit both together; don't let one drift from the other.
- **`site/downloads/*.zip` is a generated snapshot**, not source — see `site/README.md` for the regeneration command. Don't hand-edit it, and regenerate it (rather than leaving it stale) whenever `app_files/` or the top-level build-kit files change and someone will deploy `site/`.

## Testing / verification

There's no CI configured in this kit. Before proposing changes:
- Run `python -m py_compile` (or just import) on any touched `app_files/*.py` to catch syntax errors, since the build scripts won't surface those until a full PyInstaller run.
- If you can't run PyInstaller yourself (e.g. wrong host OS for the script you touched), say so explicitly rather than claiming a build was verified.

## Style

- Match existing formatting in the file you're editing rather than introducing a new style (this codebase doesn't run a formatter in CI).
- Keep the three build scripts structurally parallel — same step numbering in their `echo` banners, same `--add-data` ordering — so future diffs between them stay easy to read.
