# The Steward

The Steward is a Godot 4.7 simulation prototype about readable autonomous
village life in a magical Jajce-inspired valley. The project is built as a
living systems garden: simulation state is authoritative, while scenes provide
presentation, navigation, and interaction geometry.

## Quick start

Requirements:

- Godot 4.7.x;
- Python 3;
- the pinned development tools from `requirements-dev.txt`.

Set up the local tools with `uv`:

```bash
uv venv .venv
uv pip install -r requirements-dev.txt
```

`uv` discovers the project-local `.venv` on both macOS and Windows, so the
same setup commands work in a shell or PowerShell.

Open `project.godot` in Godot 4.7 and run the main scene.

## Quality gate

Run the complete local gate before committing.

macOS:

```bash
./tools/quality.sh
```

Windows PowerShell:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\quality.ps1
```

For a faster changed-GDScript formatting and lint pass, while still running
the Godot checks and scenarios:

```bash
./tools/quality.sh --changed
```

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\quality.ps1 -Changed
```

Auto-format all game-owned GDScript with `./tools/fix_format.sh` on macOS. On
Windows:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\fix_format.ps1
```

The gate enforces Godot 4.7, the pinned formatter and linter, headless project
scenarios, and the vendored GUT suite. See
[`docs/local_quality_gate.md`](docs/local_quality_gate.md) for setup and
troubleshooting.

## Project guide

- [`AGENTS.md`](AGENTS.md) — development loop, architecture rules, validation,
  documentation, and Git expectations;
- [`docs/PROJECT_CONTEXT.md`](docs/PROJECT_CONTEXT.md) — vision, current
  implementation, and constraints;
- [`docs/ARCHITECTURE_OVERVIEW.md`](docs/ARCHITECTURE_OVERVIEW.md) — runtime
  ownership and dependency map;
- [`docs/LEARNING_ROADMAP.md`](docs/LEARNING_ROADMAP.md) — milestone order and
  the current next slice;
- [`docs/README.md`](docs/README.md) — complete documentation map.

Start with the current code and tests when they disagree with a plan, preserve
in-progress work, and prefer one complete gameplay proof over a broad
abstraction.