From 267d4151739dfcaf8d2311fdd6ba1ab5382ab98d Mon Sep 17 00:00:00 2001
From: Jeroen Schweitzer <jpmschweitzer@gmail.com>
Date: Fri, 13 Feb 2026 01:19:29 +0100
Subject: [PATCH] feat(simulation): implement content loader Phase 2 (#408)

Extend content loader to read and instantiate real YAML content into
ECS entities. 2-phase spawn pipeline: Phase 1 creates entities with
core components (Want, Tolerance, Contentment, Personality, Tells,
Skills), Phase 2 resolves cross-references (Relationships, Secrets,
Information via KnowledgeGraph, DailyRoutine).

Loads enums, entity attributes, pools, templates, triangles, and NPC
profiles. Handles stub files gracefully. 7 integration tests against
real content files plus edge case tests for invalid data.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 server/Cargo.lock               |   32 +
 server/Cargo.toml               |    1 +
 server/src/content/loader.rs    |  619 ++++++++++++++++++
 server/src/content/mod.rs       |   85 +++
 server/src/content/spawn.rs     | 1041 +++++++++++++++++++++++++++++++
 server/src/content/types.rs     |  555 ++++++++++++++++
 server/src/lib.rs               |    1 +
 server/src/npc/mod.rs           |    1 +
 server/tests/content_loading.rs |  405 ++++++++++++
 9 files changed, 2740 insertions(+)
 create mode 100644 server/src/content/loader.rs
 create mode 100644 server/src/content/mod.rs
 create mode 100644 server/src/content/spawn.rs
 create mode 100644 server/src/content/types.rs
 create mode 100644 server/tests/content_loading.rs

diff --git a/server/Cargo.lock b/server/Cargo.lock
index f397f2e21..13d7040f3 100644
--- a/server/Cargo.lock
+++ b/server/Cargo.lock
@@ -616,6 +616,12 @@ dependencies = [
  "num-traits",
 ]
 
+[[package]]
+name = "itoa"
+version = "1.0.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92ecc6618181def0457392ccd0ee51198e065e016d1d527a7ac1b6dc7c1f09d2"
+
 [[package]]
 name = "js-sys"
 version = "0.3.85"
@@ -902,6 +908,12 @@ version = "1.0.22"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
 
+[[package]]
+name = "ryu"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f"
+
 [[package]]
 name = "semver"
 version = "1.0.27"
@@ -938,6 +950,19 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "serde_yaml"
+version = "0.9.34+deprecated"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6a8b1a1a2ebf674015cc02edccce75287f1a0130d394307b36743c2f5d504b47"
+dependencies = [
+ "indexmap",
+ "itoa",
+ "ryu",
+ "serde",
+ "unsafe-libyaml",
+]
+
 [[package]]
 name = "settled-reach-server"
 version = "0.1.0"
@@ -950,6 +975,7 @@ dependencies = [
  "rand_chacha",
  "rmp-serde",
  "serde",
+ "serde_yaml",
  "thiserror",
  "tracing",
  "tracing-subscriber",
@@ -1164,6 +1190,12 @@ version = "0.2.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ebc1c04c71510c7f702b52b7c350734c9ff1295c464a03335b00bb84fc54f853"
 
+[[package]]
+name = "unsafe-libyaml"
+version = "0.2.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "673aac59facbab8a9007c7f6108d11f63b603f7cabff99fabf650fea5c32b861"
+
 [[package]]
 name = "uuid"
 version = "1.20.0"
diff --git a/server/Cargo.toml b/server/Cargo.toml
index 61e535a49..57af583e8 100644
--- a/server/Cargo.toml
+++ b/server/Cargo.toml
@@ -7,6 +7,7 @@ edition = "2021"
 bevy_ecs = "0.18"
 bevy_app = "0.18"
 serde = { version = "1", features = ["derive"] }
+serde_yaml = "0.9"
 rmp-serde = "1"
 bincode = "1"
 rand = "0.9"
diff --git a/server/src/content/loader.rs b/server/src/content/loader.rs
new file mode 100644
index 000000000..868d0e9cc
--- /dev/null
+++ b/server/src/content/loader.rs
@@ -0,0 +1,619 @@
+//! Content discovery and deserialization.
+//!
+//! Reads content.yaml, discovers campaigns and districts via directory
+//! structure, deserializes YAML files into intermediate content types.
+//! Comment-only YAML files (stubs) are skipped gracefully.
+
+use std::collections::BTreeMap;
+use std::path::{Path, PathBuf};
+
+use crate::content::types::*;
+
+/// All content loaded from disk, organized by district.
+/// Inserted as a bevy Resource after loading completes.
+#[derive(Debug, Default)]
+pub struct ContentStore {
+    pub manifest: Option<ContentManifest>,
+    pub districts: BTreeMap<String, DistrictContent>,
+}
+
+/// Content for a single district.
+#[derive(Debug, Default)]
+pub struct DistrictContent {
+    pub meta: Option<DistrictMeta>,
+    pub district_path: PathBuf,
+    pub pools: Vec<Pool>,
+    pub templates: Vec<Template>,
+    pub triangles: Vec<Triangle>,
+    pub npc_profiles: Vec<NpcProfile>,
+    pub locations: Vec<Location>,
+    pub routines: Option<RoutineFile>,
+    pub dialogue_pools: Vec<DialoguePool>,
+    pub monologue_pools: Vec<MonologuePool>,
+}
+
+/// Errors that can occur during content loading.
+#[derive(Debug, thiserror::Error)]
+pub enum ContentError {
+    #[error("IO error: {path}: {source}")]
+    Io {
+        path: PathBuf,
+        source: std::io::Error,
+    },
+    #[error("YAML parse error: {path}: {source}")]
+    Yaml {
+        path: PathBuf,
+        source: serde_yaml::Error,
+    },
+    #[error("Content manifest not found at {0}")]
+    ManifestNotFound(PathBuf),
+}
+
+/// Load all content from the given root directory.
+///
+/// The root should contain `content.yaml` and the campaign directories.
+/// Comment-only YAML stubs are skipped (logged at debug level).
+pub fn load_content(content_root: &Path) -> Result<ContentStore, ContentError> {
+    let mut store = ContentStore::default();
+
+    // 1. Load content manifest
+    let manifest_path = content_root.join("content.yaml");
+    if !manifest_path.exists() {
+        return Err(ContentError::ManifestNotFound(manifest_path));
+    }
+    let manifest: ContentManifest = load_yaml(&manifest_path)?;
+
+    // 2. Discover districts for each enabled campaign
+    for campaign in &manifest.campaigns {
+        if !campaign.enabled {
+            tracing::debug!("Skipping disabled campaign: {}", campaign.id);
+            continue;
+        }
+
+        let campaign_path = content_root.join(&campaign.path);
+        let district_dirs = discover_districts(&campaign_path);
+
+        for district_dir in district_dirs {
+            let district_id = derive_district_id(content_root, &district_dir);
+            tracing::info!("Loading district: {} from {:?}", district_id, district_dir);
+
+            let content = load_district(&district_dir)?;
+            store.districts.insert(district_id, content);
+        }
+    }
+
+    store.manifest = Some(manifest);
+    Ok(store)
+}
+
+/// Discover district directories by recursively searching for district.yaml.
+fn discover_districts(campaign_path: &Path) -> Vec<PathBuf> {
+    let mut districts = Vec::new();
+    let systems_path = campaign_path.join("systems");
+    if systems_path.is_dir() {
+        walk_for_districts(&systems_path, &mut districts);
+    }
+    // BTreeMap ordering guarantees deterministic district processing,
+    // but sort the discovery order too for consistency.
+    districts.sort();
+    districts
+}
+
+/// Recursively walk directories looking for district.yaml files.
+fn walk_for_districts(dir: &Path, results: &mut Vec<PathBuf>) {
+    let Ok(entries) = std::fs::read_dir(dir) else {
+        return;
+    };
+
+    // Collect and sort entries for deterministic traversal order
+    let mut sorted_entries: Vec<_> = entries.filter_map(|e| e.ok()).collect();
+    sorted_entries.sort_by_key(|e| e.file_name());
+
+    for entry in sorted_entries {
+        let path = entry.path();
+        if path.is_dir() {
+            let district_yaml = path.join("district.yaml");
+            if district_yaml.exists() {
+                results.push(path);
+            } else {
+                walk_for_districts(&path, results);
+            }
+        }
+    }
+}
+
+/// Derive a district ID from its filesystem path.
+/// e.g. campaigns/main/systems/krenn/stations/sova/districts/transit → krenn.sova.transit
+fn derive_district_id(content_root: &Path, district_dir: &Path) -> String {
+    let rel = district_dir
+        .strip_prefix(content_root)
+        .unwrap_or(district_dir);
+    let components: Vec<&str> = rel
+        .components()
+        .filter_map(|c| c.as_os_str().to_str())
+        .collect();
+
+    // Extract meaningful path segments: system, station, district name
+    // Path pattern: campaigns/{id}/systems/{system}/stations/{station}/districts/{district}
+    let mut parts = Vec::new();
+    let mut iter = components.iter().peekable();
+    while let Some(&segment) = iter.next() {
+        match segment {
+            "systems" | "stations" | "districts" => {
+                if let Some(&&name) = iter.peek() {
+                    parts.push(name.to_string());
+                    iter.next();
+                }
+            }
+            _ => {}
+        }
+    }
+
+    if parts.is_empty() {
+        // Fallback: use the directory name
+        district_dir
+            .file_name()
+            .and_then(|n| n.to_str())
+            .unwrap_or("unknown")
+            .to_string()
+    } else {
+        parts.join(".")
+    }
+}
+
+/// Load all content for a single district directory.
+fn load_district(district_dir: &Path) -> Result<DistrictContent, ContentError> {
+    let mut content = DistrictContent {
+        district_path: district_dir.to_path_buf(),
+        ..Default::default()
+    };
+
+    // District metadata
+    let meta_path = district_dir.join("district.yaml");
+    if meta_path.exists() {
+        match load_yaml::<DistrictMeta>(&meta_path) {
+            Ok(meta) => content.meta = Some(meta),
+            Err(e) => tracing::warn!("Failed to parse district metadata: {}", e),
+        }
+    }
+
+    // Pools
+    let pools_path = district_dir.join("pools.yaml");
+    if pools_path.exists() {
+        match load_yaml::<PoolFile>(&pools_path) {
+            Ok(pool_file) => content.pools = pool_file.pools,
+            Err(e) => tracing::warn!("Failed to parse pools: {}", e),
+        }
+    }
+
+    // Templates
+    let templates_dir = district_dir.join("templates");
+    if templates_dir.is_dir() {
+        content.templates = load_yaml_dir::<Template>(&templates_dir);
+    }
+
+    // Triangles
+    let triangles_dir = district_dir.join("triangles");
+    if triangles_dir.is_dir() {
+        content.triangles = load_yaml_dir::<Triangle>(&triangles_dir);
+    }
+
+    // NPC profiles
+    let npcs_dir = district_dir.join("npcs");
+    if npcs_dir.is_dir() {
+        content.npc_profiles = load_yaml_dir::<NpcProfile>(&npcs_dir);
+    }
+
+    // Locations
+    let locations_dir = district_dir.join("locations");
+    if locations_dir.is_dir() {
+        content.locations = load_yaml_dir::<Location>(&locations_dir);
+    }
+
+    // Routines
+    let routines_path = district_dir.join("routines").join("schedules.yaml");
+    if routines_path.exists() {
+        match load_yaml::<RoutineFile>(&routines_path) {
+            Ok(routines) => content.routines = Some(routines),
+            Err(e) => tracing::debug!("Skipping routines (stub or invalid): {}", e),
+        }
+    }
+
+    // Dialogue pools
+    let dialogue_dir = district_dir.join("dialogue");
+    if dialogue_dir.is_dir() {
+        content.dialogue_pools = load_yaml_recursive::<DialoguePool>(&dialogue_dir);
+    }
+
+    // Monologue pools
+    let monologue_dir = district_dir.join("monologue");
+    if monologue_dir.is_dir() {
+        content.monologue_pools = load_yaml_recursive::<MonologuePool>(&monologue_dir);
+    }
+
+    let npc_count = content.npc_profiles.len();
+    let triangle_count = content.triangles.len();
+    let template_count = content.templates.len();
+    let pool_count = content.pools.len();
+    let dialogue_count = content.dialogue_pools.len();
+    let monologue_count = content.monologue_pools.len();
+
+    tracing::info!(
+        "District loaded: {} NPCs, {} triangles, {} templates, {} pools, {} dialogue pools, {} monologue pools",
+        npc_count, triangle_count, template_count, pool_count, dialogue_count, monologue_count
+    );
+
+    Ok(content)
+}
+
+/// Load and parse a single YAML file.
+fn load_yaml<T: serde::de::DeserializeOwned>(path: &Path) -> Result<T, ContentError> {
+    let text = std::fs::read_to_string(path).map_err(|e| ContentError::Io {
+        path: path.to_path_buf(),
+        source: e,
+    })?;
+    serde_yaml::from_str(&text).map_err(|e| ContentError::Yaml {
+        path: path.to_path_buf(),
+        source: e,
+    })
+}
+
+/// Load all YAML files in a directory (non-recursive), skipping stubs.
+fn load_yaml_dir<T: serde::de::DeserializeOwned>(dir: &Path) -> Vec<T> {
+    let Ok(entries) = std::fs::read_dir(dir) else {
+        return Vec::new();
+    };
+
+    let mut sorted_entries: Vec<_> = entries.filter_map(|e| e.ok()).collect();
+    sorted_entries.sort_by_key(|e| e.file_name());
+
+    let mut results = Vec::new();
+    for entry in sorted_entries {
+        let path = entry.path();
+        if path.extension().and_then(|e| e.to_str()) != Some("yaml") {
+            continue;
+        }
+        match load_yaml::<T>(&path) {
+            Ok(item) => results.push(item),
+            Err(e) => {
+                // Check if this is a comment-only stub
+                if is_comment_only_file(&path) {
+                    tracing::debug!("Skipping stub file: {:?}", path);
+                } else {
+                    tracing::warn!("Failed to parse {:?}: {}", path, e);
+                }
+            }
+        }
+    }
+    results
+}
+
+/// Load all YAML files recursively under a directory, skipping stubs.
+fn load_yaml_recursive<T: serde::de::DeserializeOwned>(dir: &Path) -> Vec<T> {
+    let mut results = Vec::new();
+    walk_yaml_files(dir, &mut |path| {
+        match load_yaml::<T>(path) {
+            Ok(item) => results.push(item),
+            Err(e) => {
+                if is_comment_only_file(path) {
+                    tracing::debug!("Skipping stub: {:?}", path);
+                } else {
+                    tracing::warn!("Failed to parse {:?}: {}", path, e);
+                }
+            }
+        }
+    });
+    results
+}
+
+/// Walk a directory recursively, calling the callback for each .yaml file.
+fn walk_yaml_files(dir: &Path, callback: &mut impl FnMut(&Path)) {
+    let Ok(entries) = std::fs::read_dir(dir) else {
+        return;
+    };
+
+    let mut sorted_entries: Vec<_> = entries.filter_map(|e| e.ok()).collect();
+    sorted_entries.sort_by_key(|e| e.file_name());
+
+    for entry in sorted_entries {
+        let path = entry.path();
+        if path.is_dir() {
+            walk_yaml_files(&path, callback);
+        } else if path.extension().and_then(|e| e.to_str()) == Some("yaml") {
+            callback(&path);
+        }
+    }
+}
+
+/// Check if a YAML file contains only comments and whitespace (stub file).
+fn is_comment_only_file(path: &Path) -> bool {
+    let Ok(text) = std::fs::read_to_string(path) else {
+        return false;
+    };
+    text.lines()
+        .all(|line| line.trim().is_empty() || line.trim().starts_with('#'))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::fs;
+
+    fn create_temp_content(dir: &Path) {
+        // Create content.yaml
+        fs::write(
+            dir.join("content.yaml"),
+            r#"version: "0.1.0"
+campaigns:
+  - id: test
+    path: campaigns/test
+    enabled: true
+    discovery:
+      districts: "systems/**/districts/*/district.yaml"
+"#,
+        )
+        .unwrap();
+
+        // Create district directory structure
+        let district_dir = dir.join("campaigns/test/systems/alpha/stations/beta/districts/gamma");
+        fs::create_dir_all(&district_dir).unwrap();
+
+        // district.yaml
+        fs::write(
+            district_dir.join("district.yaml"),
+            r#"display_name: "Test District"
+description: "A test district"
+locations: ["loc-a"]
+npc_count: 2
+"#,
+        )
+        .unwrap();
+
+        // pools.yaml
+        fs::write(
+            district_dir.join("pools.yaml"),
+            r#"pools:
+  - pool_id: "test:pool_a"
+    category: npc_role
+    candidates:
+      - npc_id: "npc:alice"
+        weight: 1
+"#,
+        )
+        .unwrap();
+
+        // triangles/
+        let tri_dir = district_dir.join("triangles");
+        fs::create_dir_all(&tri_dir).unwrap();
+        fs::write(
+            tri_dir.join("test-triangle.yaml"),
+            r#"canonical_id: test-triangle
+display_name: "Test Triangle"
+members:
+  - npc: "npc:alice"
+    role: "role-a"
+  - npc: "npc:bob"
+    role: "role-b"
+  - npc: "npc:carol"
+    role: "role-c"
+forks: []
+resolution_states: []
+"#,
+        )
+        .unwrap();
+
+        // templates/
+        let tpl_dir = district_dir.join("templates");
+        fs::create_dir_all(&tpl_dir).unwrap();
+        fs::write(
+            tpl_dir.join("test-site.yaml"),
+            r#"template_id: test-site
+display_name: "Test Site"
+location: loc-a
+role_slots:
+  - role: worker
+    display_name: "Worker"
+    count: 1
+    required: true
+"#,
+        )
+        .unwrap();
+
+        // npcs/ — one stub, one real
+        let npc_dir = district_dir.join("npcs");
+        fs::create_dir_all(&npc_dir).unwrap();
+        fs::write(
+            npc_dir.join("alice.yaml"),
+            r#"canonical_id: alice
+display_name: "Alice"
+tier: 1
+pattern: "FRIEND"
+motivation: "HANDLER"
+"#,
+        )
+        .unwrap();
+        fs::write(
+            npc_dir.join("bob.yaml"),
+            "# NPC Profile: bob\n# canonical_id: test.bob\n",
+        )
+        .unwrap();
+    }
+
+    #[test]
+    fn load_content_discovers_district() {
+        let dir = std::env::temp_dir().join("sr_content_test_discover");
+        let _ = fs::remove_dir_all(&dir);
+        fs::create_dir_all(&dir).unwrap();
+        create_temp_content(&dir);
+
+        let store = load_content(&dir).unwrap();
+        assert!(store.manifest.is_some());
+        assert_eq!(store.districts.len(), 1);
+
+        let (id, content) = store.districts.iter().next().unwrap();
+        assert_eq!(id, "alpha.beta.gamma");
+        assert!(content.meta.is_some());
+        assert_eq!(content.meta.as_ref().unwrap().display_name, "Test District");
+
+        let _ = fs::remove_dir_all(&dir);
+    }
+
+    #[test]
+    fn load_content_parses_pools() {
+        let dir = std::env::temp_dir().join("sr_content_test_pools");
+        let _ = fs::remove_dir_all(&dir);
+        fs::create_dir_all(&dir).unwrap();
+        create_temp_content(&dir);
+
+        let store = load_content(&dir).unwrap();
+        let content = store.districts.values().next().unwrap();
+        assert_eq!(content.pools.len(), 1);
+        assert_eq!(content.pools[0].pool_id, "test:pool_a");
+        assert_eq!(content.pools[0].candidates.len(), 1);
+
+        let _ = fs::remove_dir_all(&dir);
+    }
+
+    #[test]
+    fn load_content_parses_triangles() {
+        let dir = std::env::temp_dir().join("sr_content_test_triangles");
+        let _ = fs::remove_dir_all(&dir);
+        fs::create_dir_all(&dir).unwrap();
+        create_temp_content(&dir);
+
+        let store = load_content(&dir).unwrap();
+        let content = store.districts.values().next().unwrap();
+        assert_eq!(content.triangles.len(), 1);
+        assert_eq!(content.triangles[0].canonical_id, "test-triangle");
+        assert_eq!(content.triangles[0].members.len(), 3);
+
+        let _ = fs::remove_dir_all(&dir);
+    }
+
+    #[test]
+    fn load_content_skips_stub_npcs() {
+        let dir = std::env::temp_dir().join("sr_content_test_stubs");
+        let _ = fs::remove_dir_all(&dir);
+        fs::create_dir_all(&dir).unwrap();
+        create_temp_content(&dir);
+
+        let store = load_content(&dir).unwrap();
+        let content = store.districts.values().next().unwrap();
+        // Only alice.yaml should parse; bob.yaml is a stub
+        assert_eq!(content.npc_profiles.len(), 1);
+        assert_eq!(content.npc_profiles[0].canonical_id, "alice");
+
+        let _ = fs::remove_dir_all(&dir);
+    }
+
+    #[test]
+    fn load_content_parses_templates() {
+        let dir = std::env::temp_dir().join("sr_content_test_templates");
+        let _ = fs::remove_dir_all(&dir);
+        fs::create_dir_all(&dir).unwrap();
+        create_temp_content(&dir);
+
+        let store = load_content(&dir).unwrap();
+        let content = store.districts.values().next().unwrap();
+        assert_eq!(content.templates.len(), 1);
+        assert_eq!(content.templates[0].template_id, "test-site");
+        assert_eq!(content.templates[0].role_slots.len(), 1);
+
+        let _ = fs::remove_dir_all(&dir);
+    }
+
+    #[test]
+    fn derive_district_id_from_path() {
+        let root = Path::new("/content");
+        let district = Path::new("/content/campaigns/main/systems/krenn/stations/sova/districts/transit");
+        let id = derive_district_id(root, district);
+        assert_eq!(id, "krenn.sova.transit");
+    }
+
+    #[test]
+    fn is_comment_only_detects_stubs() {
+        let dir = std::env::temp_dir().join("sr_content_test_comment");
+        let _ = fs::remove_dir_all(&dir);
+        fs::create_dir_all(&dir).unwrap();
+
+        let stub = dir.join("stub.yaml");
+        fs::write(&stub, "# comment\n# another\n").unwrap();
+        assert!(is_comment_only_file(&stub));
+
+        let real = dir.join("real.yaml");
+        fs::write(&real, "key: value\n").unwrap();
+        assert!(!is_comment_only_file(&real));
+
+        let _ = fs::remove_dir_all(&dir);
+    }
+
+    #[test]
+    fn role_count_range_deserialization() {
+        // RoleCount::Range uses untagged enum — verify {min, max} object parses
+        let yaml = r#"
+template_id: test
+display_name: "Test"
+role_slots:
+  - role: worker
+    display_name: "Worker"
+    count:
+      min: 2
+      max: 4
+    required: true
+  - role: manager
+    display_name: "Manager"
+    count: 1
+    required: true
+"#;
+        let template: crate::content::types::Template =
+            serde_yaml::from_str(yaml).expect("template with RoleCount::Range should parse");
+        assert_eq!(template.role_slots.len(), 2);
+
+        match &template.role_slots[0].count {
+            crate::content::types::RoleCount::Range { min, max } => {
+                assert_eq!(*min, 2);
+                assert_eq!(*max, 4);
+            }
+            other => panic!("Expected RoleCount::Range, got {:?}", other),
+        }
+
+        match &template.role_slots[1].count {
+            crate::content::types::RoleCount::Fixed(n) => assert_eq!(*n, 1),
+            other => panic!("Expected RoleCount::Fixed, got {:?}", other),
+        }
+    }
+
+    #[test]
+    fn pool_constraint_deserialization() {
+        // PoolConstraint uses untagged enum — verify both variants parse
+        let yaml = r#"
+pools:
+  - pool_id: "test:pool"
+    category: npc_role
+    constraints:
+      - must_be_in_template: "logistics-hub"
+      - must_have_pattern: "FRIEND"
+      - bonded_character: "smuggler"
+    candidates:
+      - npc_id: "npc:alice"
+        weight: 1
+"#;
+        let pool_file: crate::content::types::PoolFile =
+            serde_yaml::from_str(yaml).expect("pool with constraints should parse");
+        assert_eq!(pool_file.pools.len(), 1);
+        assert_eq!(pool_file.pools[0].constraints.len(), 3);
+
+        // All constraints in this format are key-value strings (plain scalars)
+        // which match PoolConstraint::KeyValue
+        for constraint in &pool_file.pools[0].constraints {
+            match constraint {
+                crate::content::types::PoolConstraint::KeyValue(s) => {
+                    assert!(!s.is_empty());
+                }
+                crate::content::types::PoolConstraint::Structured(_) => {
+                    // Structured constraints are also valid
+                }
+            }
+        }
+    }
+}
diff --git a/server/src/content/mod.rs b/server/src/content/mod.rs
new file mode 100644
index 000000000..e5421fad2
--- /dev/null
+++ b/server/src/content/mod.rs
@@ -0,0 +1,85 @@
+//! Content loading and entity spawning system.
+//!
+//! Phase 2 content loader (ticket #408): loads YAML content files from disk,
+//! deserializes into intermediate types, and spawns ECS entities.
+//!
+//! Architecture (per Tyre's D-020 guidance):
+//!   1. Deserialize YAML → intermediate content types (types.rs)
+//!   2. Content discovery + loading (loader.rs) → ContentStore resource
+//!   3. ContentStore → ECS entity spawning (spawn.rs)
+//!
+//! Content schema is decoupled from ECS components. The spawn module
+//! handles the mapping between the two representations.
+
+pub mod loader;
+pub mod spawn;
+pub mod types;
+
+use bevy_app::prelude::*;
+use bevy_ecs::prelude::*;
+use std::path::PathBuf;
+
+/// Configuration for the content loader.
+/// Set the content root path before adding ContentPlugin.
+#[derive(Resource, Debug, Clone)]
+pub struct ContentConfig {
+    /// Root directory containing content.yaml and campaign directories.
+    pub content_root: PathBuf,
+}
+
+impl Default for ContentConfig {
+    fn default() -> Self {
+        Self {
+            content_root: PathBuf::from("content"),
+        }
+    }
+}
+
+/// Content loading plugin.
+///
+/// Loads content from YAML files at startup and spawns ECS entities.
+/// Requires ContentConfig resource to be inserted before the plugin runs.
+pub struct ContentPlugin;
+
+impl Plugin for ContentPlugin {
+    fn build(&self, app: &mut App) {
+        if !app.world().contains_resource::<ContentConfig>() {
+            app.insert_resource(ContentConfig::default());
+        }
+
+        app.add_systems(Startup, load_and_spawn_content);
+
+        tracing::debug!("ContentPlugin initialized");
+    }
+}
+
+/// Startup system: load content from disk and spawn entities.
+fn load_and_spawn_content(world: &mut World) {
+    let config = world.resource::<ContentConfig>().clone();
+
+    tracing::info!("Loading content from: {:?}", config.content_root);
+
+    match loader::load_content(&config.content_root) {
+        Ok(store) => {
+            let result = spawn::spawn_content(world, &store);
+            tracing::info!(
+                "Content loaded and spawned: {} NPCs",
+                result.npcs_spawned
+            );
+            // Insert the content store as a resource for runtime access
+            // (triangle queries, pool lookups, dialogue selection)
+            world.insert_resource(ContentStoreResource(store));
+        }
+        Err(e) => {
+            tracing::error!("Failed to load content: {}", e);
+            // Insert empty store so downstream systems don't panic on missing resource
+            world.insert_resource(ContentStoreResource(loader::ContentStore::default()));
+        }
+    }
+}
+
+/// Wrapper resource holding the loaded content store.
+/// Available for runtime systems that need to query content data
+/// (e.g., dialogue selection, triangle fork evaluation).
+#[derive(Resource, Debug)]
+pub struct ContentStoreResource(pub loader::ContentStore);
diff --git a/server/src/content/spawn.rs b/server/src/content/spawn.rs
new file mode 100644
index 000000000..2795887a3
--- /dev/null
+++ b/server/src/content/spawn.rs
@@ -0,0 +1,1041 @@
+//! Content → ECS entity spawning (two-phase).
+//!
+//! Maps intermediate content types from the loader into bevy_ecs
+//! Components and Resources. The separation ensures content schema
+//! changes don't require ECS component changes (and vice versa).
+//!
+//! **Phase 1** (spawn_entities): Create NPC entities with per-entity components
+//! (Want, Secret, Tolerance, Contentment, Personality, Tells, Skills). Builds
+//! the canonical_id → StableId map needed for cross-reference resolution.
+//!
+//! **Phase 2** (resolve_cross_references): Wire up components that reference
+//! other entities by canonical_id — Relationships (per-entity + global graph),
+//! KnowledgeGraph (background facts), DailyRoutine (schedules.yaml join).
+//! Requires the npc_ids map from Phase 1.
+//!
+//! NPC spawn follows the 10-axis model (D-024):
+//!   Want, Secret, Relationships, Tolerance, Routine, Information,
+//!   Contentment, Personality, Tells, Skills
+
+use bevy_ecs::prelude::*;
+use std::collections::BTreeMap;
+
+use crate::content::loader::{ContentStore, DistrictContent};
+use crate::content::types;
+use crate::knowledge::graph::KnowledgeGraph;
+use crate::knowledge::registry::{EntityRegistry, StableEntityId};
+use crate::knowledge::types::{
+    FactId, FactKnowledge, KnowledgeConfidence, KnowledgeSource, KnowledgeState, StableId,
+};
+use crate::npc;
+use crate::simulation::movement::TilePosition;
+use crate::simulation::time::DayPhase;
+
+/// Result of spawning content into the ECS world.
+#[derive(Debug, Default)]
+pub struct SpawnResult {
+    /// Number of NPC entities spawned.
+    pub npcs_spawned: u32,
+    /// Mapping from NPC canonical_id to their StableId.
+    pub npc_ids: BTreeMap<String, StableId>,
+}
+
+/// Spawn all loaded content into the ECS world.
+///
+/// This is the main entry point for content → ECS conversion.
+/// Runs Phase 1 (entity spawning) then Phase 2 (cross-reference resolution).
+pub fn spawn_content(world: &mut World, store: &ContentStore) -> SpawnResult {
+    // Phase 1: spawn entities and build canonical_id → StableId map
+    let result = spawn_entities(world, store);
+
+    // Phase 2: resolve cross-references using the id map
+    resolve_cross_references(world, store, &result);
+
+    tracing::info!(
+        "Content spawn complete: {} NPCs (phase 1), cross-references resolved (phase 2)",
+        result.npcs_spawned
+    );
+
+    result
+}
+
+// ===========================================================================
+// Phase 1: Entity spawning
+// ===========================================================================
+
+/// Phase 1: Spawn all NPC entities with per-entity components.
+/// Returns the canonical_id → StableId map for Phase 2.
+fn spawn_entities(world: &mut World, store: &ContentStore) -> SpawnResult {
+    let mut result = SpawnResult::default();
+
+    for (district_id, content) in &store.districts {
+        tracing::info!("Phase 1 — spawning entities for district: {}", district_id);
+        for profile in &content.npc_profiles {
+            spawn_npc(world, profile, &mut result);
+        }
+    }
+
+    tracing::info!("Phase 1 complete: {} NPCs spawned", result.npcs_spawned);
+    result
+}
+
+/// Spawn a single NPC entity from a content profile.
+///
+/// Maps per-entity axes of the 10-axis NPC model (D-024) to ECS components.
+/// Cross-entity axes (Relationships, Routine, Information) are handled in Phase 2.
+fn spawn_npc(world: &mut World, profile: &types::NpcProfile, result: &mut SpawnResult) {
+    let mut entity_commands = world.spawn(npc::Npc);
+
+    // Default position — will be overridden by routine system on first phase transition
+    entity_commands.insert(TilePosition::new(0, 0, 0));
+
+    // Axis 1: Want
+    if let Some(want) = &profile.want {
+        if let Some(kind) = parse_want_kind(&want.primary) {
+            entity_commands.insert(npc::Want {
+                primary: kind,
+                intensity: want.intensity.unwrap_or(5).clamp(1, 10) as u8,
+                description: want
+                    .description
+                    .clone()
+                    .unwrap_or_else(|| want.primary.clone()),
+            });
+        }
+    }
+
+    // Axis 2: Secret
+    // Content has `secret: Option<String>` — freeform narrative description.
+    // Severity defaults to Moderate (most secrets in v0.1 are career/life-threatening).
+    // known_by starts empty — runtime systems populate it when secrets are discovered.
+    if let Some(secret_text) = &profile.secret {
+        let trimmed = secret_text.trim();
+        if !trimmed.is_empty() {
+            entity_commands.insert(npc::Secret {
+                description: trimmed.to_string(),
+                severity: parse_secret_severity(trimmed),
+                known_by: Vec::new(),
+            });
+        }
+    }
+
+    // Axis 4: Tolerance threshold
+    if let Some(tolerance) = &profile.tolerance {
+        entity_commands.insert(npc::ToleranceThreshold {
+            current_stress: 0,
+            threshold: tolerance.threshold.unwrap_or(50).clamp(0, 100) as i16,
+        });
+    }
+
+    // Axis 7: Contentment
+    if let Some(contentment) = &profile.contentment {
+        entity_commands.insert(npc::Contentment {
+            level: contentment.level.unwrap_or(0).clamp(-100, 100) as i16,
+        });
+    }
+
+    // Supporting axis 1: Personality traits
+    if let Some(personality_map) = &profile.personality {
+        let traits: Vec<npc::PersonalityTrait> = personality_map
+            .keys()
+            .filter_map(|k| parse_personality_trait(k))
+            .collect();
+        if !traits.is_empty() {
+            entity_commands.insert(npc::PersonalityTraits { traits });
+        }
+    }
+
+    // Supporting axis 2: Tell system
+    if !profile.tells.is_empty() {
+        let tells: Vec<npc::Tell> = profile
+            .tells
+            .iter()
+            .map(|t| npc::Tell {
+                trigger: parse_tell_trigger(&t.trigger),
+                behavior: t.behavior.clone(),
+            })
+            .collect();
+        entity_commands.insert(npc::TellSystem { tells });
+    }
+
+    // Supporting axis 3: Skills
+    if let Some(skills) = &profile.skills {
+        let mut skill_map = BTreeMap::new();
+        if let Some(ref s) = skills.skills {
+            for (name, &level) in s {
+                if let Some(skill) = parse_skill(name) {
+                    skill_map.insert(skill, level.clamp(1, 10) as u8);
+                }
+            }
+        }
+        entity_commands.insert(npc::SkillSet {
+            skills: skill_map,
+            combat_trained: skills.combat_trained.unwrap_or(false),
+        });
+    }
+
+    // TODO: CombatCapability — no content schema type exists yet. When combat content
+    // is authored, add weapon_proficiency + combat_style mapping here.
+
+    let entity = entity_commands.id();
+
+    // Register in EntityRegistry for StableId mapping
+    let stable_id = world.resource_mut::<EntityRegistry>().register(entity);
+    world
+        .entity_mut(entity)
+        .insert(StableEntityId(stable_id));
+
+    result.npc_ids.insert(profile.canonical_id.clone(), stable_id);
+    result.npcs_spawned += 1;
+
+    tracing::debug!(
+        "Spawned NPC: {} (StableId: {:?}, tier: {})",
+        profile.canonical_id,
+        stable_id,
+        profile.tier
+    );
+}
+
+// ===========================================================================
+// Phase 2: Cross-reference resolution
+// ===========================================================================
+
+/// Phase 2: Resolve cross-references that depend on the canonical_id → StableId map.
+///
+/// This runs after all entities are spawned so that canonical_id references
+/// (e.g., relationship targets, routine NPC keys) can be resolved to StableIds.
+fn resolve_cross_references(world: &mut World, store: &ContentStore, result: &SpawnResult) {
+    for (district_id, content) in &store.districts {
+        tracing::info!(
+            "Phase 2 — resolving cross-references for district: {}",
+            district_id
+        );
+
+        // Axis 6: Information → KnowledgeGraph via with_background()
+        resolve_information(world, content, &result.npc_ids);
+
+        // Axis 3: Relationships → per-entity component + global RelationshipGraph
+        resolve_relationships(world, content, &result.npc_ids);
+
+        // Axis 5: DailyRoutine from schedules.yaml
+        resolve_routines(world, content, &result.npc_ids);
+    }
+
+    tracing::info!("Phase 2 complete");
+}
+
+/// Axis 6: Populate KnowledgeGraph with background facts from NPC information.knows.
+///
+/// Per Tyre's recommendation: populate KnowledgeGraph directly via `with_background()`,
+/// skip InformationInventory component — one source of truth.
+/// Default confidence: KnowsOf for all background knowledge (D-041).
+fn resolve_information(
+    world: &mut World,
+    content: &DistrictContent,
+    npc_ids: &BTreeMap<String, StableId>,
+) {
+    for profile in &content.npc_profiles {
+        let Some(info) = &profile.information else {
+            continue;
+        };
+        if info.knows.is_empty() {
+            continue;
+        }
+
+        let Some(&stable_id) = npc_ids.get(&profile.canonical_id) else {
+            tracing::warn!(
+                "Cannot resolve information for {}: not in npc_ids map",
+                profile.canonical_id
+            );
+            continue;
+        };
+
+        let Some(entity) = world.resource::<EntityRegistry>().to_entity(&stable_id) else {
+            continue;
+        };
+
+        // Build background facts with KnowsOf confidence
+        let facts: Vec<(FactId, FactKnowledge)> = info
+            .knows
+            .iter()
+            .map(|fact_name| {
+                (
+                    FactId(fact_name.clone()),
+                    FactKnowledge {
+                        confidence: KnowledgeConfidence::KnowsOf,
+                        source: KnowledgeSource::Background,
+                        state: KnowledgeState::Active,
+                        acquired_tick: 0,
+                    },
+                )
+            })
+            .collect();
+
+        let fact_count = facts.len();
+        let knowledge = KnowledgeGraph::with_background(facts);
+        world.entity_mut(entity).insert(knowledge);
+
+        tracing::debug!(
+            "Populated {} background facts for NPC: {}",
+            fact_count,
+            profile.canonical_id
+        );
+    }
+}
+
+/// Axis 3: Populate per-entity Relationships components and the global RelationshipGraph.
+///
+/// Two-pass resolution: canonical_id targets are resolved to StableIds using
+/// the npc_ids map from Phase 1. Unresolvable targets are logged and skipped.
+fn resolve_relationships(
+    world: &mut World,
+    content: &DistrictContent,
+    npc_ids: &BTreeMap<String, StableId>,
+) {
+    // Collect all relationship data first, then apply to world.
+    // (Avoids holding immutable + mutable borrows on world simultaneously.)
+    struct ResolvedRelationship {
+        subject_entity: Entity,
+        subject_stable_id: StableId,
+        entries: Vec<npc::Relationship>,
+    }
+
+    let registry = world.resource::<EntityRegistry>();
+    let mut resolved = Vec::new();
+
+    for profile in &content.npc_profiles {
+        if profile.relationships.is_empty() {
+            continue;
+        }
+
+        let Some(&subject_stable_id) = npc_ids.get(&profile.canonical_id) else {
+            continue;
+        };
+        let Some(subject_entity) = registry.to_entity(&subject_stable_id) else {
+            continue;
+        };
+
+        let mut entries = Vec::new();
+        for rel in &profile.relationships {
+            let Some(&target_stable_id) = npc_ids.get(&rel.target) else {
+                tracing::debug!(
+                    "Skipping relationship {}->{}: target not in npc_ids map",
+                    profile.canonical_id,
+                    rel.target
+                );
+                continue;
+            };
+
+            let kind = parse_relationship_kind(&rel.kind);
+            let trust_level = rel.trust.unwrap_or(0).clamp(-10, 10) as i8;
+
+            entries.push(npc::Relationship {
+                target_id: target_stable_id,
+                kind,
+                trust_level,
+                history: Vec::new(),
+            });
+        }
+
+        if !entries.is_empty() {
+            resolved.push(ResolvedRelationship {
+                subject_entity,
+                subject_stable_id,
+                entries,
+            });
+        }
+    }
+
+    // Apply: insert per-entity Relationships component + populate global RelationshipGraph
+    let rel_count: usize = resolved.iter().map(|r| r.entries.len()).sum();
+
+    for r in &resolved {
+        world
+            .entity_mut(r.subject_entity)
+            .insert(npc::Relationships {
+                entries: r.entries.clone(),
+            });
+    }
+
+    // Populate global RelationshipGraph resource
+    let mut graph = world
+        .get_resource::<npc::relationships::RelationshipGraph>()
+        .cloned()
+        .unwrap_or_default();
+
+    for r in &resolved {
+        for entry in &r.entries {
+            graph.set_relationship(
+                r.subject_stable_id,
+                entry.target_id,
+                npc::relationships::RelationshipEdge {
+                    kind: entry.kind,
+                    trust: entry.trust_level,
+                    history: Vec::new(),
+                    last_interaction_tick: 0,
+                },
+            );
+        }
+    }
+
+    world.insert_resource(graph);
+
+    tracing::debug!(
+        "Resolved {} relationship edges across {} NPCs",
+        rel_count,
+        resolved.len()
+    );
+}
+
+/// Axis 5: Populate DailyRoutine from routines/schedules.yaml.
+///
+/// Joins schedule entries (npc canonical_id → phase + location + tile) with
+/// spawned NPC entities. Location strings are mapped to TilePosition via
+/// tile coordinates when available; defaults to (0,0,0) otherwise.
+/// Deviations are logged and skipped for v0.1 (v0.2 scope per Tyre).
+fn resolve_routines(
+    world: &mut World,
+    content: &DistrictContent,
+    npc_ids: &BTreeMap<String, StableId>,
+) {
+    let Some(routine_file) = &content.routines else {
+        tracing::debug!("No routine schedules loaded for district — skipping");
+        return;
+    };
+
+    // Collect all resolved routines first (avoids borrow conflict with world).
+    struct ResolvedRoutine {
+        entity: Entity,
+        routine: npc::DailyRoutine,
+        npc_id: String,
+        deviation_count: usize,
+    }
+
+    let mut resolved = Vec::new();
+
+    for schedule in &routine_file.schedules {
+        let Some(&stable_id) = npc_ids.get(&schedule.npc) else {
+            tracing::debug!(
+                "Skipping routine for {}: not in npc_ids map",
+                schedule.npc
+            );
+            continue;
+        };
+        let Some(entity) = world.resource::<EntityRegistry>().to_entity(&stable_id) else {
+            continue;
+        };
+
+        let mut entries = Vec::new();
+        for entry in &schedule.entries {
+            let Some(phase) = parse_day_phase(&entry.phase) else {
+                tracing::warn!(
+                    "Unknown day phase '{}' in routine for {}",
+                    entry.phase,
+                    schedule.npc
+                );
+                continue;
+            };
+
+            // Use explicit tile coordinates if provided, otherwise default position
+            let location = entry
+                .tile
+                .as_ref()
+                .map(|t| TilePosition::new(t.x, t.y, 0))
+                .unwrap_or_else(|| TilePosition::new(0, 0, 0));
+
+            entries.push(npc::RoutineEntry {
+                phase,
+                location,
+                activity: entry
+                    .activity
+                    .clone()
+                    .unwrap_or_else(|| entry.location.clone()),
+            });
+        }
+
+        if !entries.is_empty() {
+            resolved.push(ResolvedRoutine {
+                entity,
+                routine: npc::DailyRoutine {
+                    entries,
+                    description: String::new(),
+                },
+                npc_id: schedule.npc.clone(),
+                deviation_count: schedule.deviations.len(),
+            });
+        }
+    }
+
+    // Apply routines to world
+    let routines_resolved = resolved.len();
+    for r in resolved {
+        world.entity_mut(r.entity).insert(r.routine);
+
+        if r.deviation_count > 0 {
+            tracing::debug!(
+                "Skipping {} deviations for {} (v0.2 scope)",
+                r.deviation_count,
+                r.npc_id
+            );
+        }
+    }
+
+    tracing::debug!("Resolved routines for {} NPCs", routines_resolved);
+}
+
+// ---------------------------------------------------------------------------
+// Content value → ECS enum mapping functions
+// ---------------------------------------------------------------------------
+
+/// Parse a want.primary string into a WantKind enum value.
+///
+/// Content files must use exact WantKind enum names (case-insensitive):
+/// Wealth, Safety, Knowledge, Connection, Power, Freedom, Justice, Revenge.
+/// Narrative descriptions belong in want.description, not want.primary.
+fn parse_want_kind(s: &str) -> Option<npc::WantKind> {
+    match s.to_lowercase().as_str() {
+        "wealth" => Some(npc::WantKind::Wealth),
+        "safety" => Some(npc::WantKind::Safety),
+        "knowledge" => Some(npc::WantKind::Knowledge),
+        "connection" => Some(npc::WantKind::Connection),
+        "power" => Some(npc::WantKind::Power),
+        "freedom" => Some(npc::WantKind::Freedom),
+        "justice" => Some(npc::WantKind::Justice),
+        "revenge" => Some(npc::WantKind::Revenge),
+        "happiness" => Some(npc::WantKind::Happiness),
+        other => {
+            tracing::warn!("Unknown WantKind '{}': must be one of Wealth, Safety, Knowledge, Connection, Power, Freedom, Justice, Revenge, Happiness", other);
+            None
+        }
+    }
+}
+
+fn parse_relationship_kind(s: &str) -> npc::RelationshipKind {
+    match s.to_lowercase().as_str() {
+        "colleague" => npc::RelationshipKind::Colleague,
+        "friend" => npc::RelationshipKind::Friend,
+        "rival" => npc::RelationshipKind::Rival,
+        "romantic" => npc::RelationshipKind::Romantic,
+        "family" => npc::RelationshipKind::Family,
+        "superior" => npc::RelationshipKind::Superior,
+        "subordinate" => npc::RelationshipKind::Subordinate,
+        other => {
+            tracing::warn!("Unknown relationship kind '{}', defaulting to Colleague", other);
+            npc::RelationshipKind::Colleague
+        }
+    }
+}
+
+fn parse_personality_trait(s: &str) -> Option<npc::PersonalityTrait> {
+    match s.to_lowercase().as_str() {
+        "cautious" => Some(npc::PersonalityTrait::Cautious),
+        "bold" => Some(npc::PersonalityTrait::Bold),
+        "honest" => Some(npc::PersonalityTrait::Honest),
+        "deceptive" => Some(npc::PersonalityTrait::Deceptive),
+        "compassionate" => Some(npc::PersonalityTrait::Compassionate),
+        "ruthless" => Some(npc::PersonalityTrait::Ruthless),
+        "curious" => Some(npc::PersonalityTrait::Curious),
+        "incurious" => Some(npc::PersonalityTrait::Incurious),
+        "social" => Some(npc::PersonalityTrait::Social),
+        "reclusive" => Some(npc::PersonalityTrait::Reclusive),
+        _ => None,
+    }
+}
+
+fn parse_tell_trigger(s: &str) -> npc::TellTrigger {
+    match s.to_lowercase().as_str() {
+        "stress_above_threshold" | "stressed" => npc::TellTrigger::StressAboveThreshold,
+        "always" => npc::TellTrigger::Always,
+        other => {
+            // Could be a phase-based or activity-based trigger
+            if let Some(phase) = parse_day_phase(other) {
+                npc::TellTrigger::TimeOfDay(phase)
+            } else {
+                npc::TellTrigger::DuringActivity(other.to_string())
+            }
+        }
+    }
+}
+
+fn parse_skill(s: &str) -> Option<npc::Skill> {
+    match s.to_lowercase().as_str() {
+        "combat" => Some(npc::Skill::Combat),
+        "intimidation" => Some(npc::Skill::Intimidation),
+        "medical" => Some(npc::Skill::Medical),
+        "observation" => Some(npc::Skill::Observation),
+        "persuasion" => Some(npc::Skill::Persuasion),
+        "piloting" => Some(npc::Skill::Piloting),
+        "stealth" => Some(npc::Skill::Stealth),
+        "technical" => Some(npc::Skill::Technical),
+        _ => None,
+    }
+}
+
+/// Infer secret severity from the narrative description.
+///
+/// Keyword-based heuristic: secrets mentioning criminal activity, violence,
+/// or life-threatening stakes are Major; those mentioning career/exposure are
+/// Moderate; mild social secrets are Minor. Default: Moderate.
+fn parse_secret_severity(description: &str) -> npc::SecretSeverity {
+    let lower = description.to_lowercase();
+
+    // Major: criminal, life-threatening, ring coordination, smuggling operations
+    if lower.contains("ring coordinator")
+        || lower.contains("smuggling operation")
+        || lower.contains("violently")
+        || lower.contains("killed")
+        || lower.contains("criminal")
+        || lower.contains("security breach")
+    {
+        return npc::SecretSeverity::Major;
+    }
+
+    // Minor: social embarrassment, mild secrets, ambiguous situations
+    if lower.contains("ambiguous")
+        || lower.contains("embarrassment")
+        || lower.contains("gossip")
+    {
+        return npc::SecretSeverity::Minor;
+    }
+
+    // Default: Moderate (career-threatening, covers most v0.1 secrets)
+    npc::SecretSeverity::Moderate
+}
+
+/// Parse a day phase string into the DayPhase enum.
+pub fn parse_day_phase(s: &str) -> Option<DayPhase> {
+    match s.to_lowercase().as_str() {
+        "morning" => Some(DayPhase::Morning),
+        "afternoon" => Some(DayPhase::Afternoon),
+        "evening" => Some(DayPhase::Evening),
+        "night" => Some(DayPhase::Night),
+        _ => None,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::content::types::*;
+
+    fn create_test_world() -> World {
+        let mut world = World::new();
+        world.init_resource::<EntityRegistry>();
+        world
+    }
+
+    fn create_test_profile() -> NpcProfile {
+        NpcProfile {
+            canonical_id: "test-npc".to_string(),
+            display_name: "Test NPC".to_string(),
+            tier: 1,
+            pattern: Some("FRIEND".to_string()),
+            motivation: Some("HANDLER".to_string()),
+            description: Some("A test NPC".to_string()),
+            want: Some(NpcWant {
+                primary: "Wealth".to_string(),
+                intensity: Some(7),
+                description: Some("Wants money".to_string()),
+            }),
+            secret: None,
+            relationships: vec![],
+            tolerance: Some(NpcTolerance {
+                threshold: Some(60),
+                description: None,
+            }),
+            routine: None,
+            information: None,
+            contentment: Some(NpcContentment {
+                level: Some(25),
+                description: None,
+            }),
+            personality: Some({
+                let mut m = BTreeMap::new();
+                m.insert("cautious".to_string(), "Very careful".to_string());
+                m.insert("deceptive".to_string(), "Good liar".to_string());
+                m
+            }),
+            tells: vec![NpcTell {
+                trigger: "stressed".to_string(),
+                behavior: "Taps fingers on table".to_string(),
+                visible_to: None,
+            }],
+            skills: Some(NpcSkills {
+                combat_trained: Some(false),
+                skills: Some({
+                    let mut m = BTreeMap::new();
+                    m.insert("persuasion".to_string(), 6);
+                    m.insert("stealth".to_string(), 4);
+                    m
+                }),
+            }),
+            triangle_membership: vec!["hub-power".to_string()],
+            trust_levels: None,
+            friend_arc: None,
+            dual_lens: None,
+        }
+    }
+
+    #[test]
+    fn spawn_npc_creates_entity_with_components() {
+        let mut world = create_test_world();
+        let profile = create_test_profile();
+        let mut result = SpawnResult::default();
+
+        spawn_npc(&mut world, &profile, &mut result);
+
+        assert_eq!(result.npcs_spawned, 1);
+        assert!(result.npc_ids.contains_key("test-npc"));
+
+        let stable_id = result.npc_ids["test-npc"];
+        let entity = world
+            .resource::<EntityRegistry>()
+            .to_entity(&stable_id)
+            .unwrap();
+
+        // Verify components
+        assert!(world.get::<npc::Npc>(entity).is_some());
+        assert!(world.get::<TilePosition>(entity).is_some());
+
+        let want = world.get::<npc::Want>(entity).unwrap();
+        assert_eq!(want.primary, npc::WantKind::Wealth);
+        assert_eq!(want.intensity, 7);
+
+        let tolerance = world.get::<npc::ToleranceThreshold>(entity).unwrap();
+        assert_eq!(tolerance.threshold, 60);
+
+        let contentment = world.get::<npc::Contentment>(entity).unwrap();
+        assert_eq!(contentment.level, 25);
+
+        let personality = world.get::<npc::PersonalityTraits>(entity).unwrap();
+        assert_eq!(personality.traits.len(), 2);
+
+        let tells = world.get::<npc::TellSystem>(entity).unwrap();
+        assert_eq!(tells.tells.len(), 1);
+        assert_eq!(tells.tells[0].trigger, npc::TellTrigger::StressAboveThreshold);
+
+        let skills = world.get::<npc::SkillSet>(entity).unwrap();
+        assert_eq!(skills.skills.len(), 2);
+        assert!(!skills.combat_trained);
+    }
+
+    #[test]
+    fn spawn_npc_minimal_profile() {
+        let mut world = create_test_world();
+        let profile = NpcProfile {
+            canonical_id: "minimal".to_string(),
+            display_name: "Minimal NPC".to_string(),
+            tier: 3,
+            pattern: None,
+            motivation: None,
+            description: None,
+            want: None,
+            secret: None,
+            relationships: vec![],
+            tolerance: None,
+            routine: None,
+            information: None,
+            contentment: None,
+            personality: None,
+            tells: vec![],
+            skills: None,
+            triangle_membership: vec![],
+            trust_levels: None,
+            friend_arc: None,
+            dual_lens: None,
+        };
+        let mut result = SpawnResult::default();
+
+        spawn_npc(&mut world, &profile, &mut result);
+
+        assert_eq!(result.npcs_spawned, 1);
+        let stable_id = result.npc_ids["minimal"];
+        let entity = world
+            .resource::<EntityRegistry>()
+            .to_entity(&stable_id)
+            .unwrap();
+
+        // Only Npc marker and TilePosition should be present
+        assert!(world.get::<npc::Npc>(entity).is_some());
+        assert!(world.get::<TilePosition>(entity).is_some());
+        assert!(world.get::<npc::Want>(entity).is_none());
+        assert!(world.get::<npc::ToleranceThreshold>(entity).is_none());
+    }
+
+    #[test]
+    fn parse_want_kinds() {
+        // Exact enum names (case-insensitive)
+        assert_eq!(parse_want_kind("Wealth"), Some(npc::WantKind::Wealth));
+        assert_eq!(parse_want_kind("safety"), Some(npc::WantKind::Safety));
+        assert_eq!(parse_want_kind("KNOWLEDGE"), Some(npc::WantKind::Knowledge));
+        assert_eq!(parse_want_kind("Connection"), Some(npc::WantKind::Connection));
+        assert_eq!(parse_want_kind("Power"), Some(npc::WantKind::Power));
+        assert_eq!(parse_want_kind("Freedom"), Some(npc::WantKind::Freedom));
+        assert_eq!(parse_want_kind("Justice"), Some(npc::WantKind::Justice));
+        assert_eq!(parse_want_kind("Revenge"), Some(npc::WantKind::Revenge));
+        assert_eq!(parse_want_kind("Happiness"), Some(npc::WantKind::Happiness));
+
+        // Narrative strings are NOT matched — content must use exact enum keywords
+        assert_eq!(parse_want_kind("operational stability"), None);
+        assert_eq!(parse_want_kind("control"), None);
+        assert_eq!(parse_want_kind("answers"), None);
+
+        // Unknown
+        assert_eq!(parse_want_kind("bogus"), None);
+    }
+
+    #[test]
+    fn parse_day_phases() {
+        assert_eq!(parse_day_phase("morning"), Some(DayPhase::Morning));
+        assert_eq!(parse_day_phase("Evening"), Some(DayPhase::Evening));
+        assert_eq!(parse_day_phase("unknown"), None);
+    }
+
+    #[test]
+    fn invalid_want_kind_drops_component() {
+        let mut world = create_test_world();
+        let mut profile = create_test_profile();
+        profile.want = Some(NpcWant {
+            primary: "nonexistent_desire".to_string(),
+            intensity: Some(5),
+            description: None,
+        });
+        let mut result = SpawnResult::default();
+
+        spawn_npc(&mut world, &profile, &mut result);
+
+        // NPC should still spawn
+        assert_eq!(result.npcs_spawned, 1);
+        let stable_id = result.npc_ids["test-npc"];
+        let entity = world
+            .resource::<EntityRegistry>()
+            .to_entity(&stable_id)
+            .unwrap();
+
+        // But Want component should NOT be attached (invalid kind was dropped)
+        assert!(world.get::<npc::Npc>(entity).is_some());
+        assert!(world.get::<npc::Want>(entity).is_none());
+    }
+
+    #[test]
+    fn resolve_information_populates_knowledge_graph() {
+        let mut world = create_test_world();
+
+        // Spawn an NPC with information.knows
+        let mut profile = create_test_profile();
+        profile.information = Some(NpcInformation {
+            knows: vec![
+                "contraband.ring_exists".to_string(),
+                "relationship.kael_trust".to_string(),
+            ],
+            access_tier: Some("insider".to_string()),
+        });
+
+        let mut result = SpawnResult::default();
+        spawn_npc(&mut world, &profile, &mut result);
+
+        // Run Phase 2 information resolution
+        let district = crate::content::loader::DistrictContent {
+            npc_profiles: vec![profile],
+            ..Default::default()
+        };
+        resolve_information(&mut world, &district, &result.npc_ids);
+
+        // Verify KnowledgeGraph was attached with background facts
+        let stable_id = result.npc_ids["test-npc"];
+        let entity = world
+            .resource::<EntityRegistry>()
+            .to_entity(&stable_id)
+            .unwrap();
+
+        let kg = world.get::<KnowledgeGraph>(entity).expect("KnowledgeGraph should be attached");
+        assert!(kg.knows_fact(&FactId("contraband.ring_exists".to_string())));
+        assert!(kg.knows_fact(&FactId("relationship.kael_trust".to_string())));
+        assert!(kg.fact_at_least(
+            &FactId("contraband.ring_exists".to_string()),
+            KnowledgeConfidence::KnowsOf
+        ));
+    }
+
+    #[test]
+    fn two_phase_spawn_via_spawn_content() {
+        let mut world = create_test_world();
+
+        let mut profile = create_test_profile();
+        profile.information = Some(NpcInformation {
+            knows: vec!["investigation.inspection_lapses".to_string()],
+            access_tier: None,
+        });
+
+        let mut store = ContentStore::default();
+        let mut district = crate::content::loader::DistrictContent::default();
+        district.npc_profiles.push(profile);
+        store.districts.insert("test".to_string(), district);
+
+        let result = spawn_content(&mut world, &store);
+
+        assert_eq!(result.npcs_spawned, 1);
+
+        // Verify Phase 2 ran: KnowledgeGraph should be present
+        let stable_id = result.npc_ids["test-npc"];
+        let entity = world
+            .resource::<EntityRegistry>()
+            .to_entity(&stable_id)
+            .unwrap();
+
+        let kg = world.get::<KnowledgeGraph>(entity).expect("Phase 2 should attach KnowledgeGraph");
+        assert!(kg.knows_fact(&FactId("investigation.inspection_lapses".to_string())));
+    }
+
+    #[test]
+    fn spawn_npc_with_secret() {
+        let mut world = create_test_world();
+        let mut profile = create_test_profile();
+        profile.secret = Some("Takes a cut from the smuggling operation".to_string());
+
+        let mut result = SpawnResult::default();
+        spawn_npc(&mut world, &profile, &mut result);
+
+        let stable_id = result.npc_ids["test-npc"];
+        let entity = world
+            .resource::<EntityRegistry>()
+            .to_entity(&stable_id)
+            .unwrap();
+
+        let secret = world
+            .get::<npc::Secret>(entity)
+            .expect("Secret should be attached");
+        assert!(secret.description.contains("smuggling operation"));
+        assert_eq!(secret.severity, npc::SecretSeverity::Major);
+        assert!(secret.known_by.is_empty());
+    }
+
+    #[test]
+    fn parse_secret_severity_keywords() {
+        assert_eq!(
+            parse_secret_severity("Ring coordinator who sets volume targets"),
+            npc::SecretSeverity::Major
+        );
+        assert_eq!(
+            parse_secret_severity("Handles cargo routing for the smuggling operation"),
+            npc::SecretSeverity::Major
+        );
+        assert_eq!(
+            parse_secret_severity("Security breach — unauthorized contact"),
+            npc::SecretSeverity::Major
+        );
+        assert_eq!(
+            parse_secret_severity("Spending is deliberately ambiguous"),
+            npc::SecretSeverity::Minor
+        );
+        assert_eq!(
+            parse_secret_severity("Gambling debt and compromised inspections"),
+            npc::SecretSeverity::Moderate
+        );
+    }
+
+    #[test]
+    fn parse_relationship_kinds() {
+        assert_eq!(parse_relationship_kind("friend"), npc::RelationshipKind::Friend);
+        assert_eq!(parse_relationship_kind("colleague"), npc::RelationshipKind::Colleague);
+        assert_eq!(parse_relationship_kind("family"), npc::RelationshipKind::Family);
+        assert_eq!(parse_relationship_kind("romantic"), npc::RelationshipKind::Romantic);
+        assert_eq!(parse_relationship_kind("superior"), npc::RelationshipKind::Superior);
+        assert_eq!(parse_relationship_kind("subordinate"), npc::RelationshipKind::Subordinate);
+        assert_eq!(parse_relationship_kind("rival"), npc::RelationshipKind::Rival);
+        // Unknown defaults to Colleague
+        assert_eq!(parse_relationship_kind("acquaintance"), npc::RelationshipKind::Colleague);
+    }
+
+    #[test]
+    fn resolve_relationships_populates_components_and_graph() {
+        let mut world = create_test_world();
+        world.init_resource::<npc::relationships::RelationshipGraph>();
+
+        // Spawn two NPCs
+        let mut profile_a = create_test_profile();
+        profile_a.canonical_id = "npc-a".to_string();
+        profile_a.relationships = vec![NpcRelationship {
+            target: "npc-b".to_string(),
+            kind: "friend".to_string(),
+            trust: Some(7),
+            notes: None,
+        }];
+
+        let mut profile_b = create_test_profile();
+        profile_b.canonical_id = "npc-b".to_string();
+        profile_b.relationships = vec![NpcRelationship {
+            target: "npc-a".to_string(),
+            kind: "colleague".to_string(),
+            trust: Some(3),
+            notes: None,
+        }];
+
+        let mut result = SpawnResult::default();
+        spawn_npc(&mut world, &profile_a, &mut result);
+        spawn_npc(&mut world, &profile_b, &mut result);
+
+        // Run Phase 2 relationship resolution
+        let district = crate::content::loader::DistrictContent {
+            npc_profiles: vec![profile_a, profile_b],
+            ..Default::default()
+        };
+        resolve_relationships(&mut world, &district, &result.npc_ids);
+
+        // Verify per-entity Relationships components
+        let entity_a = world
+            .resource::<EntityRegistry>()
+            .to_entity(&result.npc_ids["npc-a"])
+            .unwrap();
+        let rels_a = world.get::<npc::Relationships>(entity_a).unwrap();
+        assert_eq!(rels_a.entries.len(), 1);
+        assert_eq!(rels_a.entries[0].kind, npc::RelationshipKind::Friend);
+        assert_eq!(rels_a.entries[0].trust_level, 7);
+
+        let entity_b = world
+            .resource::<EntityRegistry>()
+            .to_entity(&result.npc_ids["npc-b"])
+            .unwrap();
+        let rels_b = world.get::<npc::Relationships>(entity_b).unwrap();
+        assert_eq!(rels_b.entries.len(), 1);
+        assert_eq!(rels_b.entries[0].kind, npc::RelationshipKind::Colleague);
+
+        // Verify global RelationshipGraph
+        let graph = world.resource::<npc::relationships::RelationshipGraph>();
+        assert_eq!(graph.edge_count(), 2);
+        let edge = graph
+            .get_relationship(&result.npc_ids["npc-a"], &result.npc_ids["npc-b"])
+            .unwrap();
+        assert_eq!(edge.kind, npc::RelationshipKind::Friend);
+        assert_eq!(edge.trust, 7);
+    }
+
+    #[test]
+    fn resolve_relationships_skips_unknown_targets() {
+        let mut world = create_test_world();
+        world.init_resource::<npc::relationships::RelationshipGraph>();
+
+        let mut profile = create_test_profile();
+        profile.relationships = vec![NpcRelationship {
+            target: "nonexistent-npc".to_string(),
+            kind: "friend".to_string(),
+            trust: Some(5),
+            notes: None,
+        }];
+
+        let mut result = SpawnResult::default();
+        spawn_npc(&mut world, &profile, &mut result);
+
+        let district = crate::content::loader::DistrictContent {
+            npc_profiles: vec![profile],
+            ..Default::default()
+        };
+        resolve_relationships(&mut world, &district, &result.npc_ids);
+
+        // No Relationships component should be attached (all targets unresolvable)
+        let entity = world
+            .resource::<EntityRegistry>()
+            .to_entity(&result.npc_ids["test-npc"])
+            .unwrap();
+        assert!(world.get::<npc::Relationships>(entity).is_none());
+    }
+}
diff --git a/server/src/content/types.rs b/server/src/content/types.rs
new file mode 100644
index 000000000..196898d9b
--- /dev/null
+++ b/server/src/content/types.rs
@@ -0,0 +1,555 @@
+//! Intermediate content types for YAML deserialization.
+//!
+//! These types mirror the JSON Schema definitions in content/_schema/.
+//! They are decoupled from ECS components — the spawn module handles
+//! the mapping from content types to bevy_ecs Components/Resources.
+//!
+//! Load order: content files → seed config → entity instantiation.
+//! Per Tyre's architecture guidance (D-020, #394).
+
+use serde::Deserialize;
+use std::collections::BTreeMap;
+
+// ---------------------------------------------------------------------------
+// Content manifest (content.yaml)
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Deserialize)]
+pub struct ContentManifest {
+    pub version: String,
+    pub campaigns: Vec<CampaignRef>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct CampaignRef {
+    pub id: String,
+    pub path: String,
+    pub enabled: bool,
+    #[serde(default)]
+    pub discovery: Option<Discovery>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct Discovery {
+    #[serde(default)]
+    pub districts: Option<String>,
+}
+
+// ---------------------------------------------------------------------------
+// District metadata (district.yaml)
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Deserialize)]
+pub struct DistrictMeta {
+    pub display_name: String,
+    pub description: String,
+    #[serde(default)]
+    pub locations: Vec<String>,
+    #[serde(default)]
+    pub npc_count: u32,
+    #[serde(default)]
+    pub canonical_id: Option<String>,
+}
+
+// ---------------------------------------------------------------------------
+// Pool configuration (pools.yaml)
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Deserialize)]
+pub struct PoolFile {
+    pub pools: Vec<Pool>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct Pool {
+    pub pool_id: String,
+    pub category: String,
+    #[serde(default)]
+    pub description: Option<String>,
+    #[serde(default)]
+    pub constraints: Vec<PoolConstraint>,
+    #[serde(default)]
+    pub candidates: Vec<PoolCandidate>,
+}
+
+/// Pool constraints are stored as key-value strings.
+/// The seed system interprets them; the loader just preserves them.
+#[derive(Debug, Deserialize)]
+#[serde(untagged)]
+pub enum PoolConstraint {
+    KeyValue(String),
+    Structured(BTreeMap<String, String>),
+}
+
+#[derive(Debug, Deserialize)]
+pub struct PoolCandidate {
+    /// NPC candidates use `npc_id`, contraband uses `id`.
+    #[serde(alias = "id")]
+    pub npc_id: Option<String>,
+    #[serde(default = "default_weight")]
+    pub weight: u32,
+}
+
+fn default_weight() -> u32 {
+    1
+}
+
+// ---------------------------------------------------------------------------
+// Template configuration (templates/*.yaml)
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Deserialize)]
+pub struct Template {
+    pub template_id: String,
+    pub display_name: String,
+    #[serde(default)]
+    pub description: Option<String>,
+    #[serde(default)]
+    pub location: Option<String>,
+    #[serde(default)]
+    pub capacity: Option<Capacity>,
+    #[serde(default)]
+    pub role_slots: Vec<RoleSlot>,
+    #[serde(default)]
+    pub v01_assignments: Option<BTreeMap<String, String>>,
+    #[serde(default)]
+    pub reference_links: Vec<ReferenceLink>,
+    #[serde(default)]
+    pub triangle_constraints: Vec<TriangleConstraint>,
+    #[serde(default)]
+    pub dialogue_pools: Vec<DialoguePoolRef>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct Capacity {
+    pub min: u32,
+    pub max: u32,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct RoleSlot {
+    pub role: String,
+    pub display_name: String,
+    #[serde(default)]
+    pub count: RoleCount,
+    #[serde(default)]
+    pub required: bool,
+    #[serde(default)]
+    pub description: Option<String>,
+    #[serde(default)]
+    pub pool_ref: Option<String>,
+    #[serde(default)]
+    pub flags: Vec<String>,
+}
+
+/// Role count can be a plain integer or a {min, max} object.
+#[derive(Debug, Deserialize)]
+#[serde(untagged)]
+pub enum RoleCount {
+    Fixed(u32),
+    Range { min: u32, max: u32 },
+}
+
+impl Default for RoleCount {
+    fn default() -> Self {
+        Self::Fixed(1)
+    }
+}
+
+#[derive(Debug, Deserialize)]
+pub struct ReferenceLink {
+    pub npc: String,
+    #[serde(default)]
+    pub owning_template: Option<String>,
+    #[serde(default)]
+    pub relationship: Option<String>,
+    #[serde(default)]
+    pub presence_phases: Vec<String>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct TriangleConstraint {
+    pub triangle: String,
+    #[serde(default)]
+    pub required_roles: Vec<String>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct DialoguePoolRef {
+    pub location: String,
+    #[serde(default)]
+    pub roles: Vec<String>,
+}
+
+// ---------------------------------------------------------------------------
+// Triangle (triangles/*.yaml) — mirrors triangle.schema.json
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Deserialize)]
+pub struct Triangle {
+    pub canonical_id: String,
+    pub display_name: String,
+    #[serde(default)]
+    pub description: Option<String>,
+    pub members: Vec<TriangleMember>,
+    #[serde(default)]
+    pub forks: Vec<Fork>,
+    #[serde(default)]
+    pub resolution_states: Vec<Resolution>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct TriangleMember {
+    pub npc: String,
+    pub role: String,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct Fork {
+    pub id: String,
+    #[serde(default)]
+    pub condition: Option<String>,
+    #[serde(default)]
+    pub outcomes: Vec<ForkOutcome>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct ForkOutcome {
+    #[serde(default)]
+    pub id: Option<String>,
+    #[serde(default)]
+    pub description: Option<String>,
+    #[serde(default)]
+    pub effects: Vec<String>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct Resolution {
+    pub id: String,
+    pub description: String,
+}
+
+// ---------------------------------------------------------------------------
+// NPC Profile (npcs/*.yaml) — mirrors npc-profile.schema.json
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Deserialize)]
+pub struct NpcProfile {
+    pub canonical_id: String,
+    pub display_name: String,
+    #[serde(default = "default_tier")]
+    pub tier: u8,
+    #[serde(default)]
+    pub pattern: Option<String>,
+    #[serde(default)]
+    pub motivation: Option<String>,
+    #[serde(default)]
+    pub description: Option<String>,
+    #[serde(default)]
+    pub want: Option<NpcWant>,
+    #[serde(default)]
+    pub secret: Option<String>,
+    #[serde(default)]
+    pub relationships: Vec<NpcRelationship>,
+    #[serde(default)]
+    pub tolerance: Option<NpcTolerance>,
+    #[serde(default)]
+    pub routine: Option<NpcRoutineSummary>,
+    #[serde(default)]
+    pub information: Option<NpcInformation>,
+    #[serde(default)]
+    pub contentment: Option<NpcContentment>,
+    #[serde(default)]
+    pub personality: Option<BTreeMap<String, String>>,
+    #[serde(default)]
+    pub tells: Vec<NpcTell>,
+    #[serde(default)]
+    pub skills: Option<NpcSkills>,
+    #[serde(default)]
+    pub triangle_membership: Vec<String>,
+    #[serde(default)]
+    pub trust_levels: Option<NpcTrustLevels>,
+    #[serde(default)]
+    pub friend_arc: Option<NpcFriendArc>,
+    #[serde(default)]
+    pub dual_lens: Option<NpcDualLens>,
+}
+
+fn default_tier() -> u8 {
+    3
+}
+
+#[derive(Debug, Deserialize)]
+pub struct NpcWant {
+    pub primary: String,
+    #[serde(default)]
+    pub intensity: Option<i32>,
+    #[serde(default)]
+    pub description: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct NpcRelationship {
+    pub target: String,
+    pub kind: String,
+    #[serde(default)]
+    pub trust: Option<i32>,
+    #[serde(default)]
+    pub notes: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct NpcTolerance {
+    #[serde(default)]
+    pub threshold: Option<i32>,
+    #[serde(default)]
+    pub description: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct NpcRoutineSummary {
+    #[serde(default)]
+    pub summary: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct NpcInformation {
+    #[serde(default)]
+    pub knows: Vec<String>,
+    #[serde(default)]
+    pub access_tier: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct NpcContentment {
+    #[serde(default)]
+    pub level: Option<i32>,
+    #[serde(default)]
+    pub description: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct NpcTell {
+    pub trigger: String,
+    pub behavior: String,
+    #[serde(default)]
+    pub visible_to: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct NpcSkills {
+    #[serde(default)]
+    pub combat_trained: Option<bool>,
+    #[serde(default)]
+    pub skills: Option<BTreeMap<String, i32>>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct NpcTrustLevels {
+    #[serde(default)]
+    pub surface: Option<String>,
+    #[serde(default)]
+    pub real: Option<String>,
+    #[serde(default)]
+    pub secret: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct NpcFriendArc {
+    pub bonded_character: String,
+    #[serde(default)]
+    pub phases: Vec<NpcFriendPhase>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct NpcFriendPhase {
+    pub phase: u8,
+    pub description: String,
+    #[serde(default)]
+    pub trigger: Option<String>,
+    #[serde(default)]
+    pub routine_deviation: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct NpcDualLens {
+    #[serde(default)]
+    pub smuggler: Option<String>,
+    #[serde(default)]
+    pub detective: Option<String>,
+}
+
+// ---------------------------------------------------------------------------
+// Location (locations/*.yaml) — mirrors location.schema.json
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Deserialize)]
+pub struct Location {
+    pub canonical_id: String,
+    pub display_name: String,
+    #[serde(default)]
+    pub description: Option<String>,
+    #[serde(default)]
+    pub tile_bounds: Option<TileBounds>,
+    #[serde(default)]
+    pub sightlines: Option<Sightlines>,
+    #[serde(default)]
+    pub ambient_sound: Option<String>,
+    #[serde(default)]
+    pub social_site: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct TileBounds {
+    pub x_min: i32,
+    pub y_min: i32,
+    pub x_max: i32,
+    pub y_max: i32,
+    pub z: i32,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct Sightlines {
+    #[serde(default)]
+    pub open: Option<bool>,
+    #[serde(default)]
+    pub notes: Option<String>,
+}
+
+// ---------------------------------------------------------------------------
+// Routine schedules (routines/schedules.yaml)
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Deserialize)]
+pub struct RoutineFile {
+    pub district: String,
+    pub schedules: Vec<NpcSchedule>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct NpcSchedule {
+    pub npc: String,
+    pub entries: Vec<RoutineEntry>,
+    #[serde(default)]
+    pub deviations: Vec<Deviation>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct RoutineEntry {
+    pub phase: String,
+    pub location: String,
+    #[serde(default)]
+    pub tile: Option<TileCoord>,
+    #[serde(default)]
+    pub activity: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct Deviation {
+    pub trigger: String,
+    #[serde(default)]
+    pub phase: Option<String>,
+    pub location: String,
+    #[serde(default)]
+    pub tile: Option<TileCoord>,
+    #[serde(default)]
+    pub activity: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct TileCoord {
+    pub x: i32,
+    pub y: i32,
+}
+
+// ---------------------------------------------------------------------------
+// Dialogue pool (dialogue/**/*.yaml)
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Deserialize)]
+pub struct DialoguePool {
+    pub location: String,
+    pub role: String,
+    pub lines: Vec<DialogueLine>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct DialogueLine {
+    pub id: String,
+    pub text: String,
+    pub role: String,
+    pub access: Vec<String>,
+    pub trust: String,
+    pub situation: Vec<String>,
+    #[serde(default)]
+    pub topic: Vec<String>,
+    #[serde(default)]
+    pub mood: Vec<String>,
+    #[serde(default)]
+    pub tags: Vec<String>,
+    #[serde(default)]
+    pub knowledge_grant: Option<KnowledgeGrant>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct KnowledgeGrant {
+    pub fact_id: String,
+    pub confidence: String,
+}
+
+// ---------------------------------------------------------------------------
+// Monologue pool (monologue/**/*.yaml)
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Deserialize)]
+pub struct MonologuePool {
+    pub character: String,
+    pub location: String,
+    pub lines: Vec<MonologueLine>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct MonologueLine {
+    pub id: String,
+    pub text: String,
+    pub trigger: String,
+    #[serde(default)]
+    pub prerequisites: Option<Prerequisites>,
+    #[serde(default)]
+    pub priority: Option<i32>,
+    #[serde(default)]
+    pub cooldown: Option<i32>,
+    #[serde(default)]
+    pub tags: Vec<String>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct Prerequisites {
+    #[serde(default)]
+    pub facts: Vec<FactPrerequisite>,
+    #[serde(default)]
+    pub entity_attributes: Vec<AttributePrerequisite>,
+    #[serde(default)]
+    pub relationship: Option<RelationshipPrerequisite>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct FactPrerequisite {
+    pub fact_id: String,
+    pub min_confidence: String,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct AttributePrerequisite {
+    pub entity: String,
+    pub key: String,
+    pub value: String,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct RelationshipPrerequisite {
+    #[serde(default)]
+    pub target: Option<String>,
+    #[serde(default)]
+    pub state: Option<String>,
+}
diff --git a/server/src/lib.rs b/server/src/lib.rs
index 631979cfe..5e3335ba0 100644
--- a/server/src/lib.rs
+++ b/server/src/lib.rs
@@ -3,6 +3,7 @@
 
 pub mod bridge;
 pub mod cause_chain;
+pub mod content;
 pub mod knowledge;
 pub mod npc;
 pub mod perception;
diff --git a/server/src/npc/mod.rs b/server/src/npc/mod.rs
index d4c4f3527..86ad505dd 100644
--- a/server/src/npc/mod.rs
+++ b/server/src/npc/mod.rs
@@ -49,6 +49,7 @@ pub enum WantKind {
     Freedom,
     Justice,
     Revenge,
+    Happiness,
 }
 
 #[derive(Component, Debug, Clone, Serialize, Deserialize)]
diff --git a/server/tests/content_loading.rs b/server/tests/content_loading.rs
new file mode 100644
index 000000000..292f4d418
--- /dev/null
+++ b/server/tests/content_loading.rs
@@ -0,0 +1,405 @@
+//! Integration test: content loading pipeline.
+//!
+//! Tests the full pipeline: discover content → deserialize YAML → spawn ECS entities.
+//! Uses real content files from content/ directory for structural content,
+//! and a test fixture for isolated NPC profile spawning.
+
+use bevy_app::prelude::*;
+use bevy_ecs::prelude::*;
+use std::collections::BTreeMap;
+use std::path::PathBuf;
+
+use settled_reach_server::content::loader::{load_content, ContentStore};
+use settled_reach_server::content::spawn::spawn_content;
+use settled_reach_server::content::types::*;
+use settled_reach_server::content::{ContentConfig, ContentPlugin, ContentStoreResource};
+use settled_reach_server::knowledge::registry::EntityRegistry;
+use settled_reach_server::npc;
+use settled_reach_server::simulation::SimulationPlugin;
+
+/// Find the content root relative to the test binary location.
+fn content_root() -> PathBuf {
+    let manifest_dir = env!("CARGO_MANIFEST_DIR");
+    PathBuf::from(manifest_dir).join("../content")
+}
+
+// -----------------------------------------------------------------------
+// Test: real content discovery and structural loading
+// -----------------------------------------------------------------------
+
+#[test]
+fn discover_real_content_structure() {
+    let root = content_root();
+    if !root.join("content.yaml").exists() {
+        // Skip if content directory is not present (e.g. CI without content)
+        eprintln!("Skipping: content directory not found at {:?}", root);
+        return;
+    }
+
+    let store = load_content(&root).expect("content loading should succeed");
+
+    // Manifest should be present
+    assert!(store.manifest.is_some());
+    let manifest = store.manifest.as_ref().unwrap();
+    assert_eq!(manifest.version, "0.1.0");
+    assert!(!manifest.campaigns.is_empty());
+
+    // At least one district should be discovered
+    assert!(!store.districts.is_empty(), "should discover at least one district");
+}
+
+#[test]
+fn load_real_transit_district() {
+    let root = content_root();
+    if !root.join("content.yaml").exists() {
+        return;
+    }
+
+    let store = load_content(&root).expect("content loading should succeed");
+
+    // The transit district should be discovered
+    let transit = store
+        .districts
+        .get("krenn.sova.transit")
+        .expect("transit district should be discovered");
+
+    // District metadata
+    assert!(transit.meta.is_some());
+    let meta = transit.meta.as_ref().unwrap();
+    assert_eq!(meta.display_name, "Sova Transit District");
+    assert_eq!(meta.npc_count, 17);
+
+    // 5 triangles from ticket #391
+    assert_eq!(transit.triangles.len(), 5);
+    let triangle_ids: Vec<&str> = transit
+        .triangles
+        .iter()
+        .map(|t| t.canonical_id.as_str())
+        .collect();
+    assert!(triangle_ids.contains(&"hub-power"));
+    assert!(triangle_ids.contains(&"worried-knowledge"));
+    assert!(triangle_ids.contains(&"bar-tensions"));
+    assert!(triangle_ids.contains(&"worried-partner"));
+    assert!(triangle_ids.contains(&"informant-question"));
+
+    // Each triangle should have exactly 3 members
+    for triangle in &transit.triangles {
+        assert_eq!(
+            triangle.members.len(),
+            3,
+            "Triangle {} should have 3 members",
+            triangle.canonical_id
+        );
+    }
+
+    // 5 pools from ticket #389
+    assert_eq!(transit.pools.len(), 5);
+    let pool_ids: Vec<&str> = transit.pools.iter().map(|p| p.pool_id.as_str()).collect();
+    assert!(pool_ids.contains(&"transit:friend_smuggler"));
+    assert!(pool_ids.contains(&"transit:friend_detective"));
+    assert!(pool_ids.contains(&"transit:bar_regulars"));
+    assert!(pool_ids.contains(&"transit:compromised_inspector"));
+    assert!(pool_ids.contains(&"transit:primary_contraband"));
+
+    // 3 templates from ticket #390
+    assert_eq!(transit.templates.len(), 3);
+    let template_ids: Vec<&str> = transit
+        .templates
+        .iter()
+        .map(|t| t.template_id.as_str())
+        .collect();
+    assert!(template_ids.contains(&"logistics-hub"));
+    assert!(template_ids.contains(&"bar"));
+    assert!(template_ids.contains(&"smuggling-ring"));
+
+    // 20 NPC profiles: 17 NPCs + 2 PC-as-NPC + 1 extended NPC (nils-davan)
+    // Populated by #398 (wiki→YAML NPC conversion)
+    assert_eq!(
+        transit.npc_profiles.len(),
+        20,
+        "Expected 20 parseable NPC profiles (17 NPCs + 2 PCs + 1 extended)"
+    );
+}
+
+#[test]
+fn verify_triangle_fork_structure() {
+    let root = content_root();
+    if !root.join("content.yaml").exists() {
+        return;
+    }
+
+    let store = load_content(&root).expect("content loading should succeed");
+    let transit = store.districts.get("krenn.sova.transit").unwrap();
+
+    // Hub power triangle: should have 1 fork with 3 outcomes
+    let hub_power = transit
+        .triangles
+        .iter()
+        .find(|t| t.canonical_id == "hub-power")
+        .expect("hub-power triangle should exist");
+
+    assert_eq!(hub_power.forks.len(), 1);
+    assert_eq!(hub_power.forks[0].id, "volume-escalation");
+    assert_eq!(hub_power.forks[0].outcomes.len(), 3);
+
+    let outcome_ids: Vec<&str> = hub_power.forks[0]
+        .outcomes
+        .iter()
+        .filter_map(|o| o.id.as_deref())
+        .collect();
+    assert!(outcome_ids.contains(&"escalate"));
+    assert!(outcome_ids.contains(&"stabilize"));
+    assert!(outcome_ids.contains(&"mediate"));
+
+    // Resolution states
+    assert_eq!(hub_power.resolution_states.len(), 3);
+}
+
+#[test]
+fn verify_pool_candidates() {
+    let root = content_root();
+    if !root.join("content.yaml").exists() {
+        return;
+    }
+
+    let store = load_content(&root).expect("content loading should succeed");
+    let transit = store.districts.get("krenn.sova.transit").unwrap();
+
+    // bar_regulars pool should have 5 candidates
+    let bar_regulars = transit
+        .pools
+        .iter()
+        .find(|p| p.pool_id == "transit:bar_regulars")
+        .expect("bar_regulars pool should exist");
+
+    assert_eq!(bar_regulars.candidates.len(), 5);
+    assert_eq!(bar_regulars.category, "npc_group");
+}
+
+#[test]
+fn verify_template_role_slots() {
+    let root = content_root();
+    if !root.join("content.yaml").exists() {
+        return;
+    }
+
+    let store = load_content(&root).expect("content loading should succeed");
+    let transit = store.districts.get("krenn.sova.transit").unwrap();
+
+    // Logistics hub should have 5 role slots
+    let hub = transit
+        .templates
+        .iter()
+        .find(|t| t.template_id == "logistics-hub")
+        .expect("logistics-hub template should exist");
+
+    assert_eq!(hub.role_slots.len(), 5);
+
+    // Should have v01_assignments
+    assert!(hub.v01_assignments.is_some());
+    let assignments = hub.v01_assignments.as_ref().unwrap();
+    assert!(assignments.contains_key("shift-supervisor"));
+}
+
+// -----------------------------------------------------------------------
+// Test: NPC spawning pipeline with test fixture data
+// -----------------------------------------------------------------------
+
+#[test]
+fn spawn_npc_from_content_store() {
+    let mut world = World::new();
+    world.init_resource::<EntityRegistry>();
+
+    // Create a minimal content store with one test NPC
+    let mut store = ContentStore::default();
+    let mut district = settled_reach_server::content::loader::DistrictContent::default();
+    district.npc_profiles.push(NpcProfile {
+        canonical_id: "test-worker".to_string(),
+        display_name: "Test Worker".to_string(),
+        tier: 2,
+        pattern: Some("ANCHOR".to_string()),
+        motivation: Some("CIVILIAN".to_string()),
+        description: Some("A test dock worker".to_string()),
+        want: Some(NpcWant {
+            primary: "Safety".to_string(),
+            intensity: Some(5),
+            description: Some("Wants a quiet life".to_string()),
+        }),
+        secret: None,
+        relationships: vec![],
+        tolerance: Some(NpcTolerance {
+            threshold: Some(70),
+            description: None,
+        }),
+        routine: None,
+        information: None,
+        contentment: Some(NpcContentment {
+            level: Some(30),
+            description: None,
+        }),
+        personality: None,
+        tells: vec![],
+        skills: Some(NpcSkills {
+            combat_trained: Some(false),
+            skills: Some({
+                let mut m = BTreeMap::new();
+                m.insert("technical".to_string(), 5);
+                m
+            }),
+        }),
+        triangle_membership: vec![],
+        trust_levels: None,
+        friend_arc: None,
+        dual_lens: None,
+    });
+    store
+        .districts
+        .insert("test.district".to_string(), district);
+
+    let result = spawn_content(&mut world, &store);
+
+    // Verify entity was spawned
+    assert_eq!(result.npcs_spawned, 1);
+    assert!(result.npc_ids.contains_key("test-worker"));
+
+    // Verify ECS components
+    let stable_id = result.npc_ids["test-worker"];
+    let entity = world
+        .resource::<EntityRegistry>()
+        .to_entity(&stable_id)
+        .unwrap();
+
+    assert!(world.get::<npc::Npc>(entity).is_some());
+
+    let want = world.get::<npc::Want>(entity).unwrap();
+    assert_eq!(want.primary, npc::WantKind::Safety);
+    assert_eq!(want.intensity, 5);
+
+    let tolerance = world.get::<npc::ToleranceThreshold>(entity).unwrap();
+    assert_eq!(tolerance.threshold, 70);
+
+    let skills = world.get::<npc::SkillSet>(entity).unwrap();
+    assert_eq!(skills.skills[&npc::Skill::Technical], 5);
+}
+
+// -----------------------------------------------------------------------
+// Test: ContentPlugin integration with bevy App
+// -----------------------------------------------------------------------
+
+#[test]
+fn content_plugin_loads_via_app() {
+    let root = content_root();
+    if !root.join("content.yaml").exists() {
+        return;
+    }
+
+    let mut app = App::new();
+    app.add_plugins(SimulationPlugin);
+    app.add_plugins(settled_reach_server::npc::NpcPlugin);
+    app.insert_resource(ContentConfig {
+        content_root: root,
+    });
+    app.add_plugins(ContentPlugin);
+
+    // Run startup systems
+    app.update();
+
+    // ContentStoreResource should be inserted
+    assert!(
+        app.world().contains_resource::<ContentStoreResource>(),
+        "ContentStoreResource should be present after startup"
+    );
+
+    let store = &app.world().resource::<ContentStoreResource>().0;
+    assert!(!store.districts.is_empty());
+}
+
+// -----------------------------------------------------------------------
+// Test: Full spawn pipeline with real content — 10-axis gap closure
+// -----------------------------------------------------------------------
+
+#[test]
+fn spawn_real_content_with_relationships_and_secrets() {
+    let root = content_root();
+    if !root.join("content.yaml").exists() {
+        return;
+    }
+
+    let mut world = World::new();
+    world.init_resource::<EntityRegistry>();
+    world.init_resource::<settled_reach_server::npc::relationships::RelationshipGraph>();
+
+    let store = load_content(&root).expect("content loading should succeed");
+    let result = spawn_content(&mut world, &store);
+
+    // All 20 profiles should spawn
+    assert_eq!(result.npcs_spawned, 20);
+    assert!(result.npc_ids.contains_key("npc:kael-davan"));
+    assert!(result.npc_ids.contains_key("npc:voss"));
+    assert!(result.npc_ids.contains_key("npc:pc-smuggler"));
+    assert!(result.npc_ids.contains_key("npc:nils-davan"));
+
+    // Verify ALL 20 NPCs have Want components (Option C: exact enum keywords in YAML)
+    let registry = world.resource::<EntityRegistry>();
+    let mut npcs_with_want = 0;
+    for (canonical_id, stable_id) in &result.npc_ids {
+        let entity = registry
+            .to_entity(stable_id)
+            .unwrap_or_else(|| panic!("{} should have an entity", canonical_id));
+        assert!(
+            world.get::<npc::Want>(entity).is_some(),
+            "NPC {} should have a Want component",
+            canonical_id
+        );
+        npcs_with_want += 1;
+    }
+    assert_eq!(npcs_with_want, 20, "All 20 NPCs should have Want components");
+
+    // Spot-check specific Want values
+    let kael_entity = registry
+        .to_entity(&result.npc_ids["npc:kael-davan"])
+        .unwrap();
+    let kael_want = world.get::<npc::Want>(kael_entity).expect("Kael should have Want");
+    assert_eq!(kael_want.primary, npc::WantKind::Safety);
+
+    // Verify Kael has a Secret component
+    let kael_secret = world
+        .get::<npc::Secret>(kael_entity)
+        .expect("Kael should have Secret");
+    assert!(kael_secret.description.contains("ring"));
+    assert_eq!(kael_secret.severity, npc::SecretSeverity::Major);
+
+    // Verify Kael has Relationships (7 defined in YAML)
+    let kael_rels = world
+        .get::<npc::Relationships>(kael_entity)
+        .expect("Kael should have Relationships");
+    assert!(
+        kael_rels.entries.len() >= 5,
+        "Kael should have at least 5 resolved relationships, got {}",
+        kael_rels.entries.len()
+    );
+
+    // Verify Kael has KnowledgeGraph (background facts from information.knows)
+    let kael_kg = world
+        .get::<settled_reach_server::knowledge::graph::KnowledgeGraph>(kael_entity)
+        .expect("Kael should have KnowledgeGraph");
+    assert!(kael_kg.knows_fact(&settled_reach_server::knowledge::types::FactId(
+        "contraband.ring_exists".to_string()
+    )));
+
+    // Verify global RelationshipGraph was populated
+    let graph = world.resource::<settled_reach_server::npc::relationships::RelationshipGraph>();
+    assert!(
+        graph.edge_count() >= 20,
+        "Expected at least 20 relationship edges, got {}",
+        graph.edge_count()
+    );
+
+    // Verify Nils (off-stage) also has correct data
+    let nils_entity = world
+        .resource::<EntityRegistry>()
+        .to_entity(&result.npc_ids["npc:nils-davan"])
+        .unwrap();
+    let nils_want = world.get::<npc::Want>(nils_entity).expect("Nils should have Want");
+    assert_eq!(nils_want.primary, npc::WantKind::Power);
+}