# Agent working guide for The Steward

This repository is a Godot 4.7 simulation prototype. Treat it as a living
systems project, not a content dump. The expected working style is:

## Default development loop

1. Read the relevant roadmap/docs before changing code.
   - Start with `docs/README.md`.
   - Use `docs/LEARNING_ROADMAP.md` for the current next item.
   - Use focused plans such as `docs/RESOURCE_NODE_MIGRATION.md` only within
     their stated scope.
2. Inspect the current code and tests before assuming roadmap status is still
   accurate. The user often changes things in parallel.
3. Implement the smallest useful vertical slice.
   - Prefer functional systems progress over broad polish.
   - Avoid deep rabbit holes unless the current slice needs them.
   - Keep Jajce visual/design work bounded; prioritize simulation behavior,
     validation, WorldEnvironment ambience, and readable presentation.
4. Validate with the local quality gate.
5. Update the smallest relevant docs after completing a phase or decision.
6. Commit with a conventional commit message.

## Validation

Only Godot 4.7 matters for this project.

Use the project quality gate from PowerShell:

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

For changed-file quick checks:

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

The quality scripts isolate Godot's user profile under `logs/quality/godot_profile`
so headless Godot 4.7 can run without crashing on blocked Windows app-data paths.
Do not remove that behavior.

Useful extra checks:

```powershell
git diff --check
```

If touching `main.tscn` or runtime wiring, also do a direct Godot 4.7 headless
boot when practical.

## Architecture direction

Preserve the simulation/presentation boundary.

- Simulation state owns authority: resources, storage, NPC inventory, events,
  task state, target IDs, positions, RNG streams, and save records.
- World nodes are presentation and interaction geometry. They may register or
  bind state, but they should not become the only owner of persistent facts.
- NPCs store stable IDs, not `NodePath`s or node references.
- Target discovery should go through `ActiveWorldAdapter` and
  `ActionTargetResolver`.
- Visual movement belongs to `WorldViewManager`/`NpcVisual`; decision and task
  execution belong to the simulation systems.

When adding a system, first prove the contract with one real gameplay use case.
Do not extract generic frameworks before multiple real consumers justify them.

## Resource and target rules

Do not reintroduce abstract food/wood task-zone fallbacks.

Current resource gathering should use finite `ResourceNode` instances:

- food: berries, animal camps, village stock, future farms/crops;
- wood: trees, wood piles, future forestry contexts.

Resource additions should preserve:

- stable unique IDs;
- food/wood coverage;
- meaningful placement context;
- reachable interaction points;
- `safety_risk`, `comfort_distance`, and `discovery_priority` metadata;
- clear player interaction ranges so nearby storage/activity/resource targets
  do not overlap accidentally.

Storage uses `StorageNode`. Rest, study, and patrol use `ActivitySite`. Do not
turn these back into generic marker zones.

## Testing expectations

Add or update headless scenarios when a change affects:

- resource conservation;
- target selection or reservations;
- save/load or schema behavior;
- navigation/reachability assumptions;
- player/NPC parity;
- deterministic continuation;
- UI/debug state that represents real simulation facts.

Keep tests deterministic. Prefer fixed seeds and stable IDs.

## Documentation expectations

Update docs when the implemented behavior changes the roadmap, architecture, or
current contract. Keep updates local:

- `docs/LEARNING_ROADMAP.md` for next-item sequencing and milestone status;
- `docs/RESOURCE_NODE_MIGRATION.md` for resource-target migration status;
- `docs/SIMULATION_STATE_SCHEMA.md` for serialized state changes;
- `docs/SIMULATION_DEFINITIONS.md` for action/profession/ID contracts;
- `docs/BUILD_IN_PUBLIC_PLAN.md` for Jajce/demo/readability slices;
- `docs/decisions/` only for durable architectural decisions.

Do not duplicate full status tables across many docs. If docs and code differ,
trust code/tests first, then update docs.

## Git expectations

Preserve user changes. Check `git status --short` before editing and before
committing. Do not use destructive cleanup commands unless explicitly asked.

Use conventional commits, for example:

- `feat: validate expanded resource discovery`
- `fix: stabilize godot 4.7 headless validation`
- `docs: capture agent workflow`

Commit only after validation relevant to the change has passed.

## Product taste

The project is aiming for a readable, magical simulation garden that can grow
into a larger systemic game. Prefer honest visible cause-and-effect:

- NPCs should walk to real resources, storage, and activity sites.
- UI/debug overlays should explain actual simulation state.
- Beauty work should represent real state rather than fake activity.
- Each slice should leave the project easier to reason about than before.
