Update AGENTS.md

AGENTS.md

@@ -5,23 +5,61 @@ Godot 4.6 idle-game; code is GDScript + `.tscn` scenes.
 Use `GODOT_BIN` for your local editor binary (e.g. `godot`, `godot4`, or full path).
 Run project: `"$GODOT_BIN" --path .`
 Headless smoke/lint parse: `"$GODOT_BIN" --headless --path . --quit`
-Script syntax check (single script): `"$GODOT_BIN" --headless --check-only --script res://big_number.gd`
-Tests: no test framework is currently committed (`tests/` and `addons/gut` are absent).
-Single-test command: N/A right now; if GUT is added, use `"$GODOT_BIN" --headless --path . -s res://addons/gut/gut_cmdln.gd -gtest=res://tests/<file>.gd`.
+Script syntax check (single script): `./scripts/check_syntax.sh <path>` (e.g. `./scripts/check_syntax.sh res://core/level_game_state.gd`)
+Run single test: `./scripts/run_test.sh res://tests/<file>.gd`
+Run all tests: `./scripts/run_all.sh`
+Tests are custom headless scripts in `tests/` using `LevelGameState` simulation (no GUT).
 
 ## Architecture And Structure
-`project.godot` defines autoload singletons: `GameState` (runtime currency state + save/load) and `CurrencyGeneratorDatabase` (loads `generator_data.json`).
-`big_number.gd` (`class_name BigNumber`) is the internal numeric API for huge-value math, comparisons, formatting, and serialization.
-`big_number_museum.tscn` + `big_number_museum.gd` is the current main playable scene/prototype UI.
-`currency_generator.gd`, `currency_label.gd`, and `big_number_progress_bar.gd` are UI/gameplay adapters that react to `GameState` signals.
-Persistence is local JSON only: `user://idle_save.json`; there is no external DB/server/backend.
+
+### No Autoloads
+There are **no autoload singletons**. All state lives in scene nodes. The project was fully decoupled from globals.
+
+### Main Scene
+`run/main_scene` points to `docs/gyms/tiny_sword/tiny_sword.tscn` (uid `dadeowsvaywpp`). This is the canonical playable scene. `docs/museums/big_number_museum.tscn` is a secondary prototype/testing scene.
+
+### Core Systems (`core/`)
+- **`core/big_number.gd`** — `class_name BigNumber`: numeric API for huge-value math, comparisons, formatting, and serialization (`{m: float, e: int}` scientific notation).
+- **`core/level_game_state.gd`** — `class_name LevelGameState` (extends `Node`): the central runtime state node. Owns all currency balances, generator states, buff levels, goal completion, research XP, prestige buff unlocks, and save/load. Assigned catalogue resources via `@export`:
+  - `currency_catalogue` → `CurrencyCatalogue` (defines all currencies)
+  - `buff_catalogue` → `BuffCatalogue` (generator buffs)
+  - `goal_catalogue` → `GoalCatalogue` (achievement goals)
+  - `research_catalogue` → `ResearchCatalogue` (research tracks)
+  - `prestige_buff_catalogue` → `PrestigeBuffCatalogue` (permanent prestige upgrades)
+- **`core/edge_scroll_camera.gd`** — camera with edge-scrolling and zoom.
+
+### Subsystems (`core/<name>/`)
+Each subsystem has its own directory with a `README.md`:
+- **`core/currency/`** — `Currency` resource, `CurrencyCatalogue` resource, `currency_panel.gd` UI.
+- **`core/generator/`** — `CurrencyGenerator` (production node), `CurrencyGeneratorData` (balancing resource), `GeneratorBuffData` (upgrades), `ResearchBuffCalculator` (static utility), `generator_container.gd` UI.
+- **`core/goals/`** — `GoalData` (achievement resource), `GoalRequirementData` (individual criteria), `current_goal_panel.gd` UI.
+- **`core/prestige/`** — `PrestigeManager` (child node of `LevelGameState` managing resets + multipliers), `PrestigeConfig`, `PrestigeBuffNode` (DAG graph node), `PrestigeBuffCatalogue`, UI panels (`prestige_panel`, `prestige_progress_bar`, `prestige_buff_graph_panel` with tiles).
+- **`core/research/`** — `ResearchData` resource (XP thresholds, production multipliers per level), `ResearchCatalogue`, `research_panel.gd` + `research_row.gd` UI.
+
+### Content Is Data-Driven (`docs/gyms/`)
+All gameplay content (currencies, generators/buildings, buffs, goals, research, prestige config) is defined as `.tres` resource files under `docs/gyms/tiny_sword/` and composed in `tiny_sword.tscn`. No hardcoded JSON data files.
+
+### Root-Level UI Helpers
+- `currency_label.gd`, `currency_tile.tscn` — reusable currency display components.
+- `big_number_progress_bar.gd` / `.tscn` — progress bar for BigNumber values.
+- `generator_buff_tile.gd` / `.tscn` — individual buff upgrade tile.
+- `goals_debug_ui.gd` / `.tscn` — debug overlay for goal state.
+
+### Persistence
+Local JSON only: `LevelGameState` saves to the path set in its `save_file_path` export (e.g. `user://tiny_sword_save.json`). No external DB/server/backend. Save format version is currently 8.
+
+### Testing
+Custom headless test scripts in `tests/` that instantiate `LevelGameState` directly (no scene tree needed). Helper scripts in `scripts/`:
+- `check_syntax.sh` — single-file Godot syntax check.
+- `run_test.sh` — run a single test script headless.
+- `run_all.sh` — run all tests.
 
 ## Code Style And Conventions
 Prefer typed GDScript (`var x: Type`, `func f() -> void`) and keep shared models/components as `class_name` scripts.
 Naming: `snake_case` for vars/functions/signals, `PascalCase` for classes, `UPPER_SNAKE_CASE` for constants.
 Follow existing Godot style: tabs/consistent indentation, early returns, and short functions grouped by purpose.
 When reading files/JSON, always guard `FileAccess.open(...)` and validate parsed types before indexing.
-Use signals (already in `GameState`) for UI updates instead of polling or cross-node direct mutation.
+Use signals (emitted by `LevelGameState`) for UI updates instead of polling or cross-node direct mutation.
 No Cursor/Claude/Windsurf/Cline/Goose/Copilot rule files were found in this repository, so this file is the canonical agent guidance.
 Avoid trivial one-line wrapper/helper functions that only forward or repack data. Inline the logic at the real call site unless the wrapper adds meaningful abstraction or is reused enough to justify it.
-Resource type safety: Use the specific resource. Avoid as much as possible explicit `Resource` usage. 
+Resource type safety: Use the specific resource type. Avoid the bare `Resource` type. Prefer `Currency`, `CurrencyGeneratorData`, `GeneratorBuffData`, `GoalData`, `ResearchData`, `PrestigeBuffNode`, etc.