Document Seminole UE 5.8 architecture (ARCHITECTURE.md + 8 ADRs) and scaffold C++ project, Git LFS and .gitignore

diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000..a6ff67c
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,13 @@
+# Git LFS: large binary assets for the Unreal Engine project.
+# Run `git lfs install` once before cloning or pulling (see README).
+*.uasset filter=lfs diff=lfs merge=lfs -text
+*.umap filter=lfs diff=lfs merge=lfs -text
+*.fbx filter=lfs diff=lfs merge=lfs -text
+*.wav filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
+*.tga filter=lfs diff=lfs merge=lfs -text
+*.psd filter=lfs diff=lfs merge=lfs -text
+*.blend filter=lfs diff=lfs merge=lfs -text
+*.spp filter=lfs diff=lfs merge=lfs -text
+*.sbs filter=lfs diff=lfs merge=lfs -text
+*.sbsar filter=lfs diff=lfs merge=lfs -text
diff --git a/.gitignore b/.gitignore
index dd6e803..ecab79a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,3 +2,23 @@ node_modules/
 dist/
 *.log
 .DS_Store
+
+# Unreal Engine: generated, cached and IDE files only (project assets and settings stay tracked)
+Binaries/
+Intermediate/
+Saved/
+DerivedDataCache/
+Build/Receipts/
+.vs/
+.vscode/
+.idea/
+*.sln
+*.suo
+*.VC.db
+*.VC.opendb
+*.sdf
+*.opensdf
+*.xcodeproj
+*.xcworkspace
+*.code-workspace
+*.generated.h
diff --git a/Config/DefaultEngine.ini b/Config/DefaultEngine.ini
new file mode 100644
index 0000000..03aa992
--- /dev/null
+++ b/Config/DefaultEngine.ini
@@ -0,0 +1,21 @@
+[/Script/EngineSettings.GameMapsSettings]
+; No startup, default or server maps are set: Content/Maps is empty until the first map ticket lands.
+; GlobalDefaultGameMode is left at the engine default for the same reason.
+
+[/Script/HardwareTargeting.HardwareTargetingSettings]
+TargetedHardwareClass=Desktop
+AppliedTargetedHardwareClass=Desktop
+DefaultGraphicsPerformance=Maximum
+AppliedDefaultGraphicsPerformance=Maximum
+
+[/Script/Engine.RendererSettings]
+r.GenerateMeshDistanceFields=True
+r.DynamicGlobalIlluminationMethod=1
+r.ReflectionMethod=1
+r.Shadow.Virtual.Enable=1
+r.DefaultFeature.AutoExposure.ExtendDefaultLuminanceRange=True
+
+[/Script/Engine.UserInterfaceSettings]
+bAuthorizeAutomaticWidgetVariableCreation=False
+FontDPIPreset=Standard
+FontDPI=72
diff --git a/Config/DefaultGame.ini b/Config/DefaultGame.ini
new file mode 100644
index 0000000..73d3654
--- /dev/null
+++ b/Config/DefaultGame.ini
@@ -0,0 +1,7 @@
+[/Script/EngineSettings.GeneralProjectSettings]
+ProjectName=Seminole
+ProjectID=4C1B9E2A4F3D4B7E8A6C2D1F0E9B8A7C
+CompanyName=Seminole contributors
+Description=A co-op survival game set in the Florida Everglades around 1900.
+ProjectVersion=0.1.0
+CopyrightNotice=Copyright Seminole contributors. MIT licence.
diff --git a/Config/DefaultInput.ini b/Config/DefaultInput.ini
new file mode 100644
index 0000000..66c1186
--- /dev/null
+++ b/Config/DefaultInput.ini
@@ -0,0 +1,4 @@
+[/Script/Engine.InputSettings]
+DefaultPlayerInputClass=/Script/EnhancedInput.EnhancedPlayerInput
+DefaultInputComponentClass=/Script/EnhancedInput.EnhancedInputComponent
+; Input Actions and Input Mapping Contexts are data assets and land under Content/ with the first character ticket.
diff --git a/Content/AI/.gitkeep b/Content/AI/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/Content/Audio/.gitkeep b/Content/Audio/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/Content/Characters/.gitkeep b/Content/Characters/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/Content/Environments/.gitkeep b/Content/Environments/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/Content/Items/.gitkeep b/Content/Items/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/Content/Maps/.gitkeep b/Content/Maps/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/Content/Missions/.gitkeep b/Content/Missions/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/Content/UI/.gitkeep b/Content/UI/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/Content/Weapons/.gitkeep b/Content/Weapons/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/Plugins/.gitkeep b/Plugins/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/README.md b/README.md
index f97df80..5dd1a83 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,32 @@
 # seminole
 Seminole is a 3d game where the user is part of a Seminole tribe in the 1900s
 
+## Unreal Engine project
+
+The shipping game is built with **Unreal Engine 5.8** (`Seminole.uproject`,
+C++ module `Seminole` under `Source/`, content under `Content/`). The
+technical foundation is documented in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+and the decisions behind it in [docs/adr/](docs/adr/README.md). The UE project
+is currently a skeleton: no gameplay, maps or plugins yet.
+
+Binary assets go through **Git LFS**. Install it once, *before* cloning or
+pulling, so LFS files are fetched instead of pointer stubs:
+
+```sh
+git lfs install
+git clone https://github.com/nabledhq/seminole.git
+```
+
+If you cloned before installing LFS, run `git lfs install` and then
+`git lfs pull` inside the repository.
+
+To open the project, install Unreal Engine 5.8 with a C++ toolchain,
+right-click `Seminole.uproject` and generate project files, then build the
+`SeminoleEditor` target and open the `.uproject`.
+
+The browser prototype below is a preview and design sandbox and keeps working
+independently of the Unreal project.
+
 ## Playing
 
 The game runs in the browser using [Babylon.js](https://www.babylonjs.com/)
@@ -93,6 +119,16 @@ See [ASSETS_LICENSES.md](ASSETS_LICENSES.md).
 ## Project layout
 
 ```
+Seminole.uproject       Unreal Engine 5.8 project (module Seminole; no plugins enabled yet)
+Source/                 UE C++: Seminole.Target.cs, SeminoleEditor.Target.cs and the Seminole module
+  Seminole/             Module stub plus one README-only folder per planned system
+Content/                UE assets (AI, Characters, Environments, Items, Maps, Missions, Weapons, UI, Audio); empty for now
+Config/                 UE DefaultEngine.ini, DefaultGame.ini, DefaultInput.ini
+Plugins/                Project plugins (none yet)
+docs/ARCHITECTURE.md    Technical foundation of the Unreal project
+docs/adr/               Architecture decision records
+.gitattributes          Git LFS rules for binary assets
+
 index.html              Page shell, HUD, hover prompt and the How to Play panel container
 src/main.js             Entry point: checks for WebGL and starts the game
 src/engine/             Babylon.js runtime
diff --git a/Seminole.uproject b/Seminole.uproject
new file mode 100644
index 0000000..2222045
--- /dev/null
+++ b/Seminole.uproject
@@ -0,0 +1,17 @@
+{
+	"FileVersion": 3,
+	"EngineAssociation": "5.8",
+	"Category": "",
+	"Description": "Seminole: a co-op survival game set in the Florida Everglades around 1900.",
+	"Modules": [
+		{
+			"Name": "Seminole",
+			"Type": "Runtime",
+			"LoadingPhase": "Default",
+			"AdditionalDependencies": [
+				"Engine"
+			]
+		}
+	],
+	"Plugins": []
+}
diff --git a/Source/Seminole.Target.cs b/Source/Seminole.Target.cs
new file mode 100644
index 0000000..8588ac1
--- /dev/null
+++ b/Source/Seminole.Target.cs
@@ -0,0 +1,16 @@
+// Copyright Seminole contributors. MIT licence; see LICENSE.
+
+using UnrealBuildTool;
+using System.Collections.Generic;
+
+public class SeminoleTarget : TargetRules
+{
+	public SeminoleTarget(TargetInfo Target) : base(Target)
+	{
+		Type = TargetType.Game;
+		DefaultBuildSettings = BuildSettingsVersion.Latest;
+		IncludeOrderVersion = EngineIncludeOrderVersion.Latest;
+
+		ExtraModuleNames.Add("Seminole");
+	}
+}
diff --git a/Source/Seminole/AI/README.md b/Source/Seminole/AI/README.md
new file mode 100644
index 0000000..b781bb7
--- /dev/null
+++ b/Source/Seminole/AI/README.md
@@ -0,0 +1,6 @@
+# AI
+
+Infected AI: StateTree assets' C++ tasks, conditions and evaluators, AI Perception setup (sight and hearing) and NavMesh movement. The state flow is Idle -> Wander -> Hear Noise -> Investigate -> Detect Player -> Chase -> Attack -> Lose Player -> Search -> Wander.
+
+No code lives here yet; this folder fixes where the system lands when its ticket is funded.
+See [docs/ARCHITECTURE.md](../../../docs/ARCHITECTURE.md).
diff --git a/Source/Seminole/Characters/README.md b/Source/Seminole/Characters/README.md
new file mode 100644
index 0000000..356cc0e
--- /dev/null
+++ b/Source/Seminole/Characters/README.md
@@ -0,0 +1,6 @@
+# Characters
+
+Player and NPC characters: the base character class, Enhanced Input bindings, movement and animation hooks.
+
+No code lives here yet; this folder fixes where the system lands when its ticket is funded.
+See [docs/ARCHITECTURE.md](../../../docs/ARCHITECTURE.md).
diff --git a/Source/Seminole/Combat/README.md b/Source/Seminole/Combat/README.md
new file mode 100644
index 0000000..65c28b0
--- /dev/null
+++ b/Source/Seminole/Combat/README.md
@@ -0,0 +1,6 @@
+# Combat
+
+Weapons, melee and ranged attacks, damage application and hit reactions. Attacks emit noise events.
+
+No code lives here yet; this folder fixes where the system lands when its ticket is funded.
+See [docs/ARCHITECTURE.md](../../../docs/ARCHITECTURE.md).
diff --git a/Source/Seminole/Community/README.md b/Source/Seminole/Community/README.md
new file mode 100644
index 0000000..a976504
--- /dev/null
+++ b/Source/Seminole/Community/README.md
@@ -0,0 +1,6 @@
+# Community
+
+The player camp as a community: villagers, their roles and needs, and camp upgrades between day and night phases.
+
+No code lives here yet; this folder fixes where the system lands when its ticket is funded.
+See [docs/ARCHITECTURE.md](../../../docs/ARCHITECTURE.md).
diff --git a/Source/Seminole/Interaction/README.md b/Source/Seminole/Interaction/README.md
new file mode 100644
index 0000000..5d4fe7e
--- /dev/null
+++ b/Source/Seminole/Interaction/README.md
@@ -0,0 +1,6 @@
+# Interaction
+
+Interactable actors and the interaction component: pick up, use, open, board a canoe.
+
+No code lives here yet; this folder fixes where the system lands when its ticket is funded.
+See [docs/ARCHITECTURE.md](../../../docs/ARCHITECTURE.md).
diff --git a/Source/Seminole/Inventory/README.md b/Source/Seminole/Inventory/README.md
new file mode 100644
index 0000000..60e8b9e
--- /dev/null
+++ b/Source/Seminole/Inventory/README.md
@@ -0,0 +1,6 @@
+# Inventory
+
+Items, containers, equipment slots and the data assets that describe them.
+
+No code lives here yet; this folder fixes where the system lands when its ticket is funded.
+See [docs/ARCHITECTURE.md](../../../docs/ARCHITECTURE.md).
diff --git a/Source/Seminole/Multiplayer/README.md b/Source/Seminole/Multiplayer/README.md
new file mode 100644
index 0000000..59590c1
--- /dev/null
+++ b/Source/Seminole/Multiplayer/README.md
@@ -0,0 +1,6 @@
+# Multiplayer
+
+Listen-server co-op plumbing: sessions, join flow, replication helpers and the Steam online subsystem integration (enabled in a later ticket).
+
+No code lives here yet; this folder fixes where the system lands when its ticket is funded.
+See [docs/ARCHITECTURE.md](../../../docs/ARCHITECTURE.md).
diff --git a/Source/Seminole/Persistence/README.md b/Source/Seminole/Persistence/README.md
new file mode 100644
index 0000000..2985c7d
--- /dev/null
+++ b/Source/Seminole/Persistence/README.md
@@ -0,0 +1,6 @@
+# Persistence
+
+Host-owned save game: what is saved, when, and how clients receive world state on join.
+
+No code lives here yet; this folder fixes where the system lands when its ticket is funded.
+See [docs/ARCHITECTURE.md](../../../docs/ARCHITECTURE.md).
diff --git a/Source/Seminole/Seminole.Build.cs b/Source/Seminole/Seminole.Build.cs
new file mode 100644
index 0000000..2d1f7d1
--- /dev/null
+++ b/Source/Seminole/Seminole.Build.cs
@@ -0,0 +1,22 @@
+// Copyright Seminole contributors. MIT licence; see LICENSE.
+
+using UnrealBuildTool;
+
+public class Seminole : ModuleRules
+{
+	public Seminole(ReadOnlyTargetRules Target) : base(Target)
+	{
+		PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;
+
+		PublicDependencyModuleNames.AddRange(new string[]
+		{
+			"Core",
+			"CoreUObject",
+			"Engine",
+			"InputCore",
+			"EnhancedInput"
+		});
+
+		PrivateDependencyModuleNames.AddRange(new string[] { });
+	}
+}
diff --git a/Source/Seminole/Seminole.cpp b/Source/Seminole/Seminole.cpp
new file mode 100644
index 0000000..62adeec
--- /dev/null
+++ b/Source/Seminole/Seminole.cpp
@@ -0,0 +1,6 @@
+// Copyright Seminole contributors. MIT licence; see LICENSE.
+
+#include "Seminole.h"
+#include "Modules/ModuleManager.h"
+
+IMPLEMENT_PRIMARY_GAME_MODULE(FDefaultGameModuleImpl, Seminole, "Seminole");
diff --git a/Source/Seminole/Seminole.h b/Source/Seminole/Seminole.h
new file mode 100644
index 0000000..ac66745
--- /dev/null
+++ b/Source/Seminole/Seminole.h
@@ -0,0 +1,5 @@
+// Copyright Seminole contributors. MIT licence; see LICENSE.
+
+#pragma once
+
+#include "CoreMinimal.h"
diff --git a/Source/Seminole/Survival/README.md b/Source/Seminole/Survival/README.md
new file mode 100644
index 0000000..e1f5da7
--- /dev/null
+++ b/Source/Seminole/Survival/README.md
@@ -0,0 +1,6 @@
+# Survival
+
+Health, hunger, stamina and the day/night cycle that drives the scavenge and defense phases.
+
+No code lives here yet; this folder fixes where the system lands when its ticket is funded.
+See [docs/ARCHITECTURE.md](../../../docs/ARCHITECTURE.md).
diff --git a/Source/Seminole/Vehicles/README.md b/Source/Seminole/Vehicles/README.md
new file mode 100644
index 0000000..885fe49
--- /dev/null
+++ b/Source/Seminole/Vehicles/README.md
@@ -0,0 +1,6 @@
+# Vehicles
+
+Canoe travel: a paddled watercraft with passengers, used to move between islands in the swamp.
+
+No code lives here yet; this folder fixes where the system lands when its ticket is funded.
+See [docs/ARCHITECTURE.md](../../../docs/ARCHITECTURE.md).
diff --git a/Source/Seminole/World/README.md b/Source/Seminole/World/README.md
new file mode 100644
index 0000000..e25e7d6
--- /dev/null
+++ b/Source/Seminole/World/README.md
@@ -0,0 +1,6 @@
+# World
+
+World Partition and PCG integration: the swamp map, biome rules, loot and spawn placement, and the shared noise event subsystem.
+
+No code lives here yet; this folder fixes where the system lands when its ticket is funded.
+See [docs/ARCHITECTURE.md](../../../docs/ARCHITECTURE.md).
diff --git a/Source/SeminoleEditor.Target.cs b/Source/SeminoleEditor.Target.cs
new file mode 100644
index 0000000..3dd4173
--- /dev/null
+++ b/Source/SeminoleEditor.Target.cs
@@ -0,0 +1,16 @@
+// Copyright Seminole contributors. MIT licence; see LICENSE.
+
+using UnrealBuildTool;
+using System.Collections.Generic;
+
+public class SeminoleEditorTarget : TargetRules
+{
+	public SeminoleEditorTarget(TargetInfo Target) : base(Target)
+	{
+		Type = TargetType.Editor;
+		DefaultBuildSettings = BuildSettingsVersion.Latest;
+		IncludeOrderVersion = EngineIncludeOrderVersion.Latest;
+
+		ExtraModuleNames.Add("Seminole");
+	}
+}
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
new file mode 100644
index 0000000..0ec1b4d
--- /dev/null
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,243 @@
+# Seminole architecture
+
+Seminole is a 1–4 player co-op survival game set in the Florida Everglades
+around 1900. Players are members of a Seminole camp: by day they travel the
+swamp by canoe and scavenge; by night they defend the camp against the
+infected. This document records the technical foundation every later
+community-funded feature builds on. Each major choice has an architecture
+decision record in [`adr/`](adr/README.md).
+
+This document describes intent. Nothing below is implemented yet; the ticket
+that implements a system owns the details and updates this file.
+
+## Engine and programming model
+
+* Unreal Engine **5.8**, desktop first (Windows, then Linux and macOS as
+  effort allows), distributed on Steam. See [ADR 0001](adr/0001-unreal-engine-5.md).
+* One game module, `Seminole`, under `Source/Seminole/`, with one subfolder
+  per system (AI, Characters, Combat, Community, Inventory, Interaction,
+  Multiplayer, Persistence, Survival, Vehicles, World). Each subfolder's
+  `README.md` states its purpose.
+* C++ for core systems: base classes, components, subsystems, replication,
+  save/load and anything performance-sensitive. Blueprint and data assets for
+  content: concrete characters, items, weapons, missions and tuning. Blueprint
+  classes derive from C++ bases and are not expected to contain system logic.
+  See [ADR 0002](adr/0002-cpp-blueprint-hybrid.md).
+* Enhanced Input for all player input; Input Actions and Mapping Contexts are
+  data assets under `Content/`.
+* No Gameplay Ability System by default. Health, stamina, damage and status
+  effects are plain components and data assets until a concrete need appears.
+  See [ADR 0007](adr/0007-no-gameplay-ability-system-by-default.md).
+
+### Intended plugins
+
+The project enables **no** plugins today (`Seminole.uproject` has an empty
+`Plugins` list). Each of the following is enabled in the later ticket that
+first needs it, never speculatively:
+
+| Plugin | Needed by |
+| --- | --- |
+| StateTree | Infected AI |
+| CommonUI | UI |
+| PCG | World generation |
+| MetaSounds | Audio |
+| OnlineSubsystemSteam | Multiplayer/Steam |
+
+## AI
+
+The infected are `ACharacter`-based actors driven by **StateTree**, perceiving
+through **AI Perception** (sight and hearing) and moving on **NavMesh**.
+See [ADR 0003](adr/0003-statetree-ai-without-massentity-at-first.md).
+
+State flow:
+
+```
+Idle -> Wander -> Hear Noise -> Investigate -> Detect Player -> Chase -> Attack -> Lose Player -> Search -> Wander
+```
+
+* `Idle` / `Wander`: low-cost ambient behaviour; wander picks reachable
+  NavMesh points near a home location.
+* `Hear Noise` / `Investigate`: a noise event (below) or a hearing stimulus
+  sets a point of interest; the infected walks there and looks around.
+* `Detect Player` / `Chase` / `Attack`: sight confirms a target; chase uses
+  NavMesh pathing; attack is a melee range check and a hit on the target.
+* `Lose Player` / `Search`: on losing sight, search around the last known
+  position for a while, then fall back to `Wander`.
+
+StateTree tasks, conditions and evaluators are C++ in `Source/Seminole/AI/`;
+the trees themselves and per-type tuning are assets under `Content/AI/`.
+AI runs on the host only (see Multiplayer); clients receive replicated
+movement and animation.
+
+## Noise event system
+
+Noise is **one shared gameplay event**, not a per-system mechanic. See
+[ADR 0004](adr/0004-noise-event-system.md).
+
+* A world subsystem (`Source/Seminole/World/`) exposes
+  `ReportNoise(Location, Loudness, Instigator, Tag)`.
+* Everything that makes noise calls it: footsteps, gunshots, melee impacts,
+  canoe paddling, doors, dropped items, campfire work.
+* The subsystem forwards each event to AI Perception's hearing sense and
+  broadcasts a delegate so other systems (audio cues, UI, missions) can react
+  to the same event.
+* Loudness is a radius in world units; falloff and material attenuation are
+  tuning details for the implementing ticket.
+
+## Large-population roadmap
+
+1. **StateTree actors first.** The vertical slice uses individual
+   `ACharacter` infected driven by StateTree. This is the simplest thing that
+   works, debuggable in the editor, and sufficient for the camp-defense scale
+   of the slice.
+2. **Cheap distance tiers.** Reduce tick rate, perception frequency and
+   animation quality for infected far from any player before touching the
+   architecture.
+3. **MassEntity as an optional later step.** If a later feature needs hordes
+   beyond what tiered actors can handle, MassEntity can represent distant
+   infected as entities and hand off to StateTree actors near players. This
+   is not planned for the vertical slice and is not a dependency of any
+   current system.
+
+## World
+
+* One persistent swamp level using **World Partition** for streaming; islands,
+  hammocks and camp sites are placed as data layers and streamed by distance.
+* **PCG** scatters vegetation, debris and loot spawn points from biome rules
+  so the swamp can grow without hand-placing every palmetto.
+* Water is traversable by canoe (see Gameplay components) and slow to wade.
+* A day/night cycle is the clock for the scavenge and defense phases
+  (Survival).
+* World code lives in `Source/Seminole/World/`; maps and PCG graphs under
+  `Content/Maps/` and `Content/Environments/`.
+
+## Multiplayer/Steam
+
+* **Listen server** for 1–4 players: one player hosts, others join. Single
+  player is a listen server with no clients. See
+  [ADR 0005](adr/0005-listen-server-and-steam.md).
+* Authority lives on the host: AI, noise, damage, inventory mutations, loot
+  and the day/night clock. Clients predict only their own movement.
+* Steam provides sessions, invites and friends-join through
+  `OnlineSubsystemSteam`; the Steam AppID and Steamworks configuration are
+  added when the Steam ticket is funded.
+* Code in `Source/Seminole/Multiplayer/`. No dedicated servers.
+
+## Persistence
+
+* A **host-owned save game**: the host's machine stores the camp, world state,
+  mission progress and every participating player's character. See
+  [ADR 0006](adr/0006-host-owned-save-game.md).
+* Saving happens at phase boundaries (end of day, end of night) and on
+  graceful exit, using `USaveGame` subclasses serialised with the engine's
+  save system.
+* Clients joining a saved session receive state through normal replication;
+  their own character is restored from the host's save when they reconnect.
+* Code in `Source/Seminole/Persistence/`.
+
+## Gameplay components
+
+Systems are `UActorComponent`s on C++ base actors, configured by data assets.
+Planned components and their folders:
+
+| Folder | Components |
+| --- | --- |
+| `Characters/` | Player and villager base characters, Enhanced Input, animation hooks |
+| `Survival/` | Health, stamina, hunger, day/night phase |
+| `Combat/` | Weapons, melee and ranged attacks, damage |
+| `Inventory/` | Items, containers, equipment |
+| `Interaction/` | Interactable actors and the interaction component |
+| `Vehicles/` | Canoe: a paddled pawn carrying passengers |
+| `Community/` | Villagers, roles, camp upgrades |
+
+Every component that can make noise reports it through the noise subsystem.
+
+## UI
+
+* **UMG** widgets built on **CommonUI** for consistent input handling across
+  keyboard/mouse and gamepad, and for a single activatable-widget stack.
+* HUD (health, stamina, time of day, noise indicator), inventory, pause and
+  session menus. Widget assets under `Content/UI/`.
+
+## Audio
+
+* **MetaSounds** for procedural, parameter-driven sound: swamp ambience that
+  follows the time of day, infected vocalisations, weapons.
+* Audio reacts to the same noise events the AI hears, so what players hear and
+  what the infected hear stay consistent.
+* Sound assets under `Content/Audio/`.
+
+## Art pipeline
+
+* Source files (`.blend`, `.spp`, `.sbs`, `.sbsar`, `.psd`) are kept in the
+  repository through Git LFS alongside the exported `.fbx`, `.png`, `.tga`
+  and `.wav` they produce.
+* Characters, environments, items and weapons each have a `Content/`
+  folder; naming and texel-density conventions are set by the first art
+  ticket.
+* The period setting (Seminole camp life around 1900) should be reviewed by
+  cultural advisors before final art is accepted.
+
+## Source control
+
+* **Git with Git LFS**. `.gitattributes` routes `.uasset`, `.umap`, `.fbx`,
+  `.wav`, `.png`, `.tga`, `.psd`, `.blend`, `.spp`, `.sbs` and `.sbsar`
+  through LFS. See [ADR 0008](adr/0008-git-lfs-before-perforce.md).
+* Binary assets cannot be merged. Until file locking is needed, coordinate
+  through tickets: one open ticket owns a given map or asset at a time. Keep
+  maps small and split content with World Partition data layers and One File
+  Per Actor to reduce conflicts.
+* `.gitignore` excludes `Binaries/`, `Intermediate/`, `Saved/`,
+  `DerivedDataCache/` and IDE files. `Content/` and `Config/` are tracked.
+* Perforce is a possible later move if LFS becomes a bottleneck; nothing in
+  the layout prevents it.
+
+## Browser strategy
+
+* The repository also contains a **Babylon.js browser prototype** (`src/`,
+  `index.html`, `package.json`, deployed to GitHub Pages by
+  `.github/workflows/nabled-play.yml`). It exists so backers can try builds
+  in a browser and it predates this document.
+* The shipping game is the Unreal Engine 5.8 project. The browser prototype
+  is a preview and design sandbox, not a second target: gameplay systems
+  are built once, in Unreal.
+* The prototype stays in the repository and keeps working; it is not deleted
+  by the UE scaffold, and the two trees do not share code. Its future
+  (keep as showcase, or retire once the UE build has playable releases) is
+  a later decision.
+* Browser-first builds of the Unreal project (Pixel Streaming or otherwise)
+  are out of scope.
+
+## Vertical slice contents and target loop
+
+Contents:
+
+* One swamp map (World Partition, PCG-scattered vegetation).
+* Canoe travel between the camp and scavenge sites.
+* A **day scavenge phase**: paddle out, explore, gather items, make noise
+  carefully, return.
+* A **night defense phase**: infected drawn by noise and light approach the
+  camp; players defend it.
+* Co-op for 1–4 players over a listen server.
+
+Target loop: wake at camp -> canoe out -> scavenge -> return before dark ->
+prepare -> survive the night -> repeat. Each loop should make the camp a
+little stronger and the night a little harder.
+
+## Deferred / Out of scope
+
+Deferred (possible later, not planned now):
+
+* MassEntity for large infected populations.
+* Gameplay Ability System.
+* Perforce.
+* Linux and macOS builds; gamepad polish beyond CommonUI defaults.
+* Retiring or re-scoping the browser prototype.
+
+Out of scope for this project:
+
+* Dedicated servers, MMO-style worlds, backend orchestration.
+* Browser-first or mobile builds, console ports.
+* Final art direction or content.
+* Any gameplay system in this ticket: AI, noise, health, inventory, weapons,
+  canoe, persistence, networking are documented here and implemented later.
diff --git a/docs/adr/0001-unreal-engine-5.md b/docs/adr/0001-unreal-engine-5.md
new file mode 100644
index 0000000..08351b8
--- /dev/null
+++ b/docs/adr/0001-unreal-engine-5.md
@@ -0,0 +1,27 @@
+# 0001. Unreal Engine 5
+
+Status: Accepted
+
+## Context
+
+Seminole needs a 3D engine for a desktop co-op survival game with a large
+streamed outdoor world, a population of AI characters, networking and a Steam
+release. The repository already holds a Babylon.js browser prototype that is
+useful for previews but is not a production game engine for this scope.
+
+## Decision
+
+Build the game on Unreal Engine **5.8**. Desktop first, distributed on Steam.
+The project is a C++ project (`Seminole.uproject`, module `Seminole`), not a
+Blueprint-only project.
+
+## Consequences
+
+* World Partition, PCG, StateTree, AI Perception, NavMesh, the replication
+  system, Enhanced Input, UMG/CommonUI and MetaSounds come with the engine;
+  the other ADRs build on them.
+* Binary assets (`.uasset`, `.umap`) require Git LFS and careful
+  coordination (see ADR 0008).
+* Contributors need an Unreal 5.8 installation and a C++ toolchain. Engine
+  version is pinned by `EngineAssociation`; upgrades are explicit tickets.
+* The browser prototype remains a preview, not a second target.
diff --git a/docs/adr/0002-cpp-blueprint-hybrid.md b/docs/adr/0002-cpp-blueprint-hybrid.md
new file mode 100644
index 0000000..a692aa3
--- /dev/null
+++ b/docs/adr/0002-cpp-blueprint-hybrid.md
@@ -0,0 +1,31 @@
+# 0002. C++ and Blueprint hybrid
+
+Status: Accepted
+
+## Context
+
+Unreal supports pure Blueprint, pure C++ and mixed projects. Seminole's
+systems (AI, noise, replication, persistence) need performance, diffable
+source and unit-testable logic. Its content (characters, items, weapons,
+missions, tuning) benefits from fast iteration by non-programmers.
+
+## Decision
+
+* **C++ for core systems**: base actor and component classes, subsystems,
+  replication, save/load, StateTree tasks and anything performance-sensitive.
+  Code lives in `Source/Seminole/<System>/`.
+* **Blueprint and data assets for content**: concrete characters, items,
+  weapons, missions, StateTree assets and tuning values. Blueprint classes
+  derive from C++ bases and contain presentation and configuration, not
+  system logic.
+* Exposed C++ API is marked `BlueprintCallable` / `BlueprintReadOnly` where
+  content needs it; everything else stays private.
+
+## Consequences
+
+* Core logic is reviewable in pull requests and merges cleanly; Blueprint
+  assets are binary and conflict-prone, so they stay thin.
+* Every system ticket delivers a C++ base plus one or more Blueprint or data
+  asset examples under `Content/`.
+* Contributors who only touch content do not need to compile C++ once a
+  build is available, but the repository remains a C++ project.
diff --git a/docs/adr/0003-statetree-ai-without-massentity-at-first.md b/docs/adr/0003-statetree-ai-without-massentity-at-first.md
new file mode 100644
index 0000000..345eafb
--- /dev/null
+++ b/docs/adr/0003-statetree-ai-without-massentity-at-first.md
@@ -0,0 +1,35 @@
+# 0003. StateTree AI without MassEntity at first
+
+Status: Accepted
+
+## Context
+
+The infected need to idle, wander, react to noise, investigate, detect,
+chase, attack, lose and search for players. Unreal offers Behavior Trees,
+StateTree, and the MassEntity framework (with StateTree-driven Mass
+processors) for very large populations. The vertical slice is one camp
+defended at night, not a city-scale horde.
+
+## Decision
+
+* Drive each infected with **StateTree** on an `ACharacter`-based actor,
+  using **AI Perception** (sight, hearing) and **NavMesh** movement.
+* The state flow is
+  `Idle -> Wander -> Hear Noise -> Investigate -> Detect Player -> Chase -> Attack -> Lose Player -> Search -> Wander`.
+* StateTree tasks, conditions and evaluators are C++ in
+  `Source/Seminole/AI/`; tree assets and tuning are under `Content/AI/`.
+* **MassEntity is not used initially.** It remains an optional later step
+  for distant or very large populations, with a hand-off to StateTree actors
+  near players.
+* Before any move to Mass, apply cheap distance tiers (tick rate, perception
+  frequency, animation quality) to far-away infected.
+
+## Consequences
+
+* The AI is debuggable with the standard editor tools and simple to reason
+  about on a listen server (host authority).
+* Population size is bounded by actor cost; this is acceptable for the slice
+  and is the explicit trade-off.
+* The `StateTree` plugin is enabled by the AI ticket, not before.
+* If Mass is adopted later, the state flow and noise interface stay the same;
+  only the representation of distant infected changes.
diff --git a/docs/adr/0004-noise-event-system.md b/docs/adr/0004-noise-event-system.md
new file mode 100644
index 0000000..7662a3f
--- /dev/null
+++ b/docs/adr/0004-noise-event-system.md
@@ -0,0 +1,32 @@
+# 0004. Noise event system
+
+Status: Accepted
+
+## Context
+
+Noise is the central tension of Seminole: scavenging quietly by day and
+holding the camp at night both depend on what the infected hear. Footsteps,
+gunshots, melee, paddling, doors, dropped items and camp work all make
+noise. If each system reported noise its own way, the AI, audio and UI would
+drift apart and tuning would be scattered.
+
+## Decision
+
+* Noise is **one shared gameplay event** handled by a single world subsystem
+  (`Source/Seminole/World/`), with an API of the form
+  `ReportNoise(Location, Loudness, Instigator, Tag)`.
+* Every noise source calls this one entry point; nothing talks to AI
+  Perception's hearing sense directly.
+* The subsystem forwards the event to AI Perception hearing and broadcasts a
+  delegate so audio, UI (noise indicator) and missions react to the same
+  event.
+* Loudness is a world-space radius; attenuation rules belong to the
+  implementing ticket.
+* Noise is authoritative on the host (see ADR 0005).
+
+## Consequences
+
+* One place to tune, log and visualise noise; one place to replicate it.
+* AI, audio and UI agree on what happened, by construction.
+* Every gameplay ticket that adds a noisy action depends on this subsystem
+  and must call it; the stub README in `Source/Seminole/World/` records this.
diff --git a/docs/adr/0005-listen-server-and-steam.md b/docs/adr/0005-listen-server-and-steam.md
new file mode 100644
index 0000000..16e5a5b
--- /dev/null
+++ b/docs/adr/0005-listen-server-and-steam.md
@@ -0,0 +1,32 @@
+# 0005. Listen server and Steam
+
+Status: Accepted
+
+## Context
+
+Seminole is co-op for 1–4 players, sold on Steam. Options are a listen
+server (one player's game hosts), dedicated servers (hosted by us or by
+players) or peer-to-peer. Dedicated servers need infrastructure and
+operations the project does not want; the player count is small and sessions
+are friend groups.
+
+## Decision
+
+* **Listen server**: the hosting player's game is the authority. Single
+  player is a listen server with no clients.
+* **Steam** (`OnlineSubsystemSteam`) provides sessions, invites and
+  friends-join. The Steam AppID and Steamworks configuration are added by
+  the Steam ticket, not now.
+* Authority on the host for AI, noise, damage, inventory mutations, loot and
+  the day/night clock. Clients predict only their own movement.
+* Code in `Source/Seminole/Multiplayer/`.
+
+## Consequences
+
+* No server infrastructure to run or pay for; sessions live and die with the
+  host.
+* Host advantage (zero latency) is accepted for a co-op game.
+* Replication is designed from the start: every gameplay system ticket
+  states what replicates and what is host-only.
+* Dedicated servers, MMO-style worlds and backend orchestration are out of
+  scope.
diff --git a/docs/adr/0006-host-owned-save-game.md b/docs/adr/0006-host-owned-save-game.md
new file mode 100644
index 0000000..c4e78a6
--- /dev/null
+++ b/docs/adr/0006-host-owned-save-game.md
@@ -0,0 +1,29 @@
+# 0006. Host-owned save game
+
+Status: Accepted
+
+## Context
+
+Progress (camp, world state, missions, characters) must survive between
+sessions. With a listen server (ADR 0005) the host already owns the
+authoritative state. Alternatives are per-player saves that must be merged,
+or a cloud/backend store.
+
+## Decision
+
+* The save game is **owned by the host**: the hosting player's machine
+  stores the camp, world state, mission progress and every participating
+  player's character, keyed by their online identity.
+* Save at phase boundaries (end of day, end of night) and on graceful exit,
+  using `USaveGame` subclasses and the engine's save system.
+* Clients receive state through replication on join; a returning client's
+  character is restored from the host's save.
+* Code in `Source/Seminole/Persistence/`.
+
+## Consequences
+
+* One consistent world per host; no merge of divergent saves.
+* A player's progress in a given camp lives with that camp's host. Players
+  who host their own camp have their own save. This is the accepted
+  trade-off; portable per-player characters are a possible later feature.
+* Steam Cloud sync of the host's save is a later, optional addition.
diff --git a/docs/adr/0007-no-gameplay-ability-system-by-default.md b/docs/adr/0007-no-gameplay-ability-system-by-default.md
new file mode 100644
index 0000000..93fd8fb
--- /dev/null
+++ b/docs/adr/0007-no-gameplay-ability-system-by-default.md
@@ -0,0 +1,28 @@
+# 0007. No Gameplay Ability System by default
+
+Status: Accepted
+
+## Context
+
+The Gameplay Ability System (GAS) is Unreal's framework for abilities,
+attributes and effects with built-in replication and prediction. It is
+powerful, but it has a steep learning curve, pervasive boilerplate and
+shapes every gameplay class around it. Seminole's needs are health, stamina,
+hunger, a few weapons, melee and some status effects, in a small co-op game.
+
+## Decision
+
+* Do **not** adopt GAS by default.
+* Model health, stamina, hunger, damage and status effects as plain
+  `UActorComponent`s and data assets in `Source/Seminole/Survival/` and
+  `Combat/`, replicated with standard property replication and RPCs.
+* Revisit if a concrete feature needs predicted abilities, stacking effects
+  with complex lifetimes, or a large ability catalogue. Adoption would be
+  its own ADR and ticket.
+
+## Consequences
+
+* Lower barrier for contributors; smaller, readable systems.
+* Some things GAS gives for free (effect stacking, attribute aggregation,
+  cue routing) are written by hand if and when needed; keep them small.
+* Full GAS adoption is explicitly out of scope for the vertical slice.
diff --git a/docs/adr/0008-git-lfs-before-perforce.md b/docs/adr/0008-git-lfs-before-perforce.md
new file mode 100644
index 0000000..2d8c800
--- /dev/null
+++ b/docs/adr/0008-git-lfs-before-perforce.md
@@ -0,0 +1,36 @@
+# 0008. Git LFS before Perforce
+
+Status: Accepted
+
+## Context
+
+Unreal projects hold many large binary assets (`.uasset`, `.umap`, textures,
+meshes, audio) that Git handles poorly without help. Perforce is the
+industry default for Unreal teams, with file locking and good editor
+integration, but it needs a server and is a poor fit for a community-funded
+open project whose contributions arrive as GitHub pull requests.
+
+## Decision
+
+* Keep **Git**, hosted on GitHub, and route binary assets through **Git
+  LFS**. `.gitattributes` tracks `*.uasset`, `*.umap`, `*.fbx`, `*.wav`,
+  `*.png`, `*.tga`, `*.psd`, `*.blend`, `*.spp`, `*.sbs` and `*.sbsar`.
+* Contributors run `git lfs install` once before cloning or pulling.
+* Avoid binary merge conflicts by process: one open ticket owns a given map
+  or asset at a time; keep maps small; use World Partition data layers and
+  One File Per Actor.
+* `.gitignore` excludes generated directories (`Binaries/`,
+  `Intermediate/`, `Saved/`, `DerivedDataCache/`) and IDE files; `Content/`
+  and `Config/` are tracked.
+
+## Consequences
+
+* The existing pull-request workflow and GitHub Pages preview keep working.
+* LFS bandwidth and storage quotas apply; large asset drops should be
+  reviewed for size (see `ASSETS_LICENSES.md` for the current limits).
+* LFS has no locking by default; coordination is social, not enforced. If
+  this becomes a bottleneck, moving to Perforce (or enabling LFS file
+  locking) is a later ticket. Nothing in the layout prevents it.
+* Files already committed before this rule (for example the screenshots in
+  `docs/screenshots/`) remain ordinary Git objects; only new matching files
+  go through LFS unless a migration is done deliberately.
diff --git a/docs/adr/README.md b/docs/adr/README.md
new file mode 100644
index 0000000..e57bf3a
--- /dev/null
+++ b/docs/adr/README.md
@@ -0,0 +1,20 @@
+# Architecture decision records
+
+Each record captures one decision behind [ARCHITECTURE.md](../ARCHITECTURE.md)
+with **Context**, **Decision** and **Consequences** headings. Records are
+numbered in order and never edited to change their meaning; a reversed
+decision gets a new record that supersedes the old one.
+
+| # | Decision |
+| --- | --- |
+| [0001](0001-unreal-engine-5.md) | Unreal Engine 5 (5.8, desktop first, Steam) |
+| [0002](0002-cpp-blueprint-hybrid.md) | C++ for core systems, Blueprint and data assets for content |
+| [0003](0003-statetree-ai-without-massentity-at-first.md) | StateTree AI without MassEntity at first |
+| [0004](0004-noise-event-system.md) | Noise as one shared gameplay event |
+| [0005](0005-listen-server-and-steam.md) | Listen server for 1–4 player co-op, Steam for sessions |
+| [0006](0006-host-owned-save-game.md) | Host-owned save game |
+| [0007](0007-no-gameplay-ability-system-by-default.md) | No Gameplay Ability System by default |
+| [0008](0008-git-lfs-before-perforce.md) | Git with Git LFS before Perforce |
+
+To add a record, copy the structure of an existing file, use the next number
+and add a row here.