The overlay's working notes, out of the working tree

They were an untracked CLAUDE.md sitting beside the code -- never committed, so
nothing had to be removed from the history. It only ever existed on one
machine, which is the opposite of documentation.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Home.md

@@ -1 +1,22 @@
-Placeholder. Replaced by the first push.
+# Kingdom Cheat: Deliverance II
+
+A desktop **overlay** for *Kingdom Come: Deliverance II* — a searchable database
+of console commands, items, perks, buffs and skills. Fill in the parameters,
+click **Copy**, paste the finished command into the game console.
+
+It does not talk to the game. It only builds command strings for the clipboard.
+
+Stack: **Tauri v2** (Rust shell) with a **React 19 / TypeScript** frontend, built
+with Vite.
+
+Source: [`Houmeres/Kingdom-Cheat-Deliverance-2`](https://git.houmeres.sk/Houmeres/Kingdom-Cheat-Deliverance-2).
+
+| Page | What it is |
+|---|---|
+| [Working-notes](Working-notes) | The rules, the repository layout, and how the data files and command builders fit together. |
+
+---
+
+This page was an untracked `CLAUDE.md` in the working tree. Unlike the other
+repositories in this org, **KCD2's history was not rewritten** — the file was
+never committed, so there was nothing in the history to remove.

Working-notes.md

@@ -0,0 +1,87 @@
+# Kingdom Cheat: Deliverance II — working notes
+
+The project's rules and layout. This page was an **untracked** `CLAUDE.md` in the
+working tree until 2026-08-08 — it was never committed, so there is no history to
+rewrite here. Nothing loads it automatically now; read it before starting work.
+
+## What this is
+
+A desktop **overlay** for *Kingdom Come: Deliverance II*. It's a searchable database of
+console commands, items, perks, buffs and skills: the user fills in parameters, clicks
+**Copy**, and pastes the finished command into the game console. It does not talk to the
+game — it only builds command strings for the clipboard.
+
+Stack: **Tauri v2** (Rust shell) + **React 19 / TypeScript** frontend, built with **Vite**.
+
+## Commands
+
+```sh
+npm install
+npm run tauri dev        # run the full app (Rust + Vite HMR)
+npm run tauri build      # release bundles (deb/AppImage on Linux, NSIS/MSI on Windows)
+npm run dev              # frontend only in a browser — see "browser fallback" below
+npm run build            # tsc typecheck + vite build (this is the only "test": there are no unit tests)
+node scripts/fetch-data.mjs   # regenerate src/data/*.json from the upstream Cheat mod
+```
+
+There is no linter and no test suite. `npm run build` (which runs `tsc`) is the check to
+run before considering frontend work done. For Rust, `cargo check` / `cargo clippy` inside
+`src-tauri/`.
+
+Windows cross-build from Linux uses cargo-xwin — see README.md "Building".
+
+## Architecture
+
+Two halves that meet at a thin IPC boundary:
+
+**Rust shell (`src-tauri/src/lib.rs`)** — `main.rs` just calls `run()`. This owns everything
+OS-level: the tray icon, the global hotkey (default `ctrl+shift+k`), and the overlay window
+(frameless, transparent, always-on-top, `visible:false` at startup — see `tauri.conf.json`).
+Key behaviors:
+- Closing the window **hides** it (`prevent_close` in `on_window_event`); the app only quits
+  from the tray menu.
+- A second process launch is an IPC toggle (`tauri_plugin_single_instance` + `--toggle` arg) —
+  this is the Wayland fallback for the unreliable global hotkey.
+- Settings persist via `tauri_plugin_store` in `settings.json`. The hotkey and `start_hidden`
+  are read on the Rust side; `set_hotkey` re-registers and rolls back to the previous hotkey
+  on failure so the overlay can never become unreachable.
+- Only four `#[tauri::command]`s are exposed: `toggle_window`, `hide_window`, `set_hotkey`,
+  `get_hotkey`. Everything else (clipboard, store, autostart) uses Tauri plugins directly
+  from JS.
+
+**Frontend (`src/`)** — `App.tsx` is a tabbed overlay: Quick / Commands / Items / Perks /
+Buffs / Skills / Settings. All game data is **vendored JSON in `src/data/`** and imported
+statically; the app is fully offline with no runtime fetches.
+
+- `src/lib/tauri.ts` — the **only** place that touches Tauri APIs. Every function has a
+  browser fallback (guarded by `inTauri`), so `npm run dev` in a plain browser is usable for
+  UI work: clipboard falls back to `navigator.clipboard`, the store to `localStorage`, and
+  window/hotkey calls become no-ops. When adding native functionality, wrap it here, not in
+  components.
+- `src/lib/commands.ts` — command-string builders and the token search (`matches`). Two
+  command *flavors* exist and are built differently:
+  - **devmode / vanilla** (`VanillaCommand`): a `{placeholder}` template filled by
+    `buildFromTemplate`. Requires the game launched with `-devmode`.
+  - **cheatmod** (`ModCommand`): built as `name arg:value` pairs by `buildFromArgs`. Requires
+    the Nexus "Cheat" mod.
+  `flavor` in Settings picks the user's preferred one; database tabs often emit *both* variants.
+- `src/tabs/databases.tsx` — Items/Perks/Buffs/Skills are all thin configs over the shared
+  `DatabaseTab` component: each provides `params` and a `build(entry, values)` that returns
+  labeled command variants. This is where the exact command syntax for each cheat type lives
+  (e.g. `cheat_add_item exact:… amount:… condition:…` vs the devmode Lua `#player.inventory:…`).
+  To change how a database command is emitted, edit the `buildX` functions here.
+- `src/types.ts` is the shared contract for all the JSON shapes and command types — read it
+  first when touching data or command logic.
+
+## Data pipeline
+
+`src/data/*.json` is **generated, not hand-edited** — except `commands-vanilla.json` and
+`quick-cheats.json`, which are hand-curated from community lists. `scripts/fetch-data.mjs`
+pulls CSV/txt dumps from the upstream `pryans/kcd2-cheat` repo and parses them:
+- a custom CSV dialect (backslash-escaped commas, quoted fields with literal newlines),
+- HTML-entity-encoded rich-text descriptions flattened to plain text,
+- the Cheat mod's `docs.txt` (BBCode) parsed into commands with args/examples,
+- command categories assigned by regex in `CATEGORY_RULES`.
+
+Output is committed so builds stay offline. Re-run the script to refresh when the upstream
+mod updates. `meta.json` records the source, mod version, and fetch timestamp.