docs: add story and OpenClaw design foundations

.claude/CLAUDE.md

@@ -271,6 +271,10 @@ Cultivation Master mechanics without a new approved design update.
 - Stable branch: `main` only receives reviewed, smoke-tested changes from `dev`
 - Daily working branch: `dev`
 - Feature work: create a separate branch/worktree from `dev`, then PR back into `dev`
+- Worktree path rule: local agent worktrees MUST live under
+  `D:\Projects\Second-Spawn\.claude\worktrees\<slug>`. Do not create sibling
+  folders such as `D:\Projects\Second-Spawn-<slug>`. Use:
+  `git worktree add .claude/worktrees/<slug> -b <branch> dev`.
 - Public repo open source from day 1
 - License: AGPL-3.0 (code) + CC-BY-NC 4.0 (assets)
 - Before opening a PR, run the local repo `code-review` skill or an equivalent

AGENTS.md

@@ -271,6 +271,10 @@ Cultivation Master mechanics without a new approved design update.
 - Stable branch: `main` only receives reviewed, smoke-tested changes from `dev`
 - Daily working branch: `dev`
 - Feature work: create a separate branch/worktree from `dev`, then PR back into `dev`
+- Worktree path rule: local agent worktrees MUST live under
+  `D:\Projects\Second-Spawn\.claude\worktrees\<slug>`. Do not create sibling
+  folders such as `D:\Projects\Second-Spawn-<slug>`. Use:
+  `git worktree add .claude/worktrees/<slug> -b <branch> dev`.
 - Public repo open source from day 1
 - License: AGPL-3.0 (code) + CC-BY-NC 4.0 (assets)
 - Before opening a PR, run the local repo `code-review` skill or an equivalent

Unity/Assets/_SecondSpawn/Editor/SecondSpawnBuildUtility.cs

@@ -0,0 +1,74 @@
+#if UNITY_EDITOR
+using System;
+using System.IO;
+using System.Linq;
+using UnityEditor;
+using UnityEditor.Build.Reporting;
+using UnityEngine;
+
+namespace SecondSpawn.EditorTools
+{
+    public static class SecondSpawnBuildUtility
+    {
+        private const string FallbackScenePath = "Assets/_SecondSpawn/Scenes/ZoneTest_Hub.unity";
+
+        [MenuItem("Second Spawn/Build/Windows Development Client")]
+        public static void BuildWindowsDevelopmentClient()
+        {
+            BuildWindowsPlayer("Windows", BuildOptions.Development | BuildOptions.AllowDebugging);
+        }
+
+        [MenuItem("Second Spawn/Build/Windows Smoke Client")]
+        public static void BuildWindowsSmokeClient()
+        {
+            BuildWindowsPlayer("WindowsSmoke", BuildOptions.Development);
+        }
+
+        private static void BuildWindowsPlayer(string folderName, BuildOptions buildOptions)
+        {
+            var outputDirectory = Path.Combine(RepoRoot(), "Builds", folderName);
+            Directory.CreateDirectory(outputDirectory);
+
+            var options = new BuildPlayerOptions
+            {
+                scenes = EnabledBuildScenes(),
+                locationPathName = Path.Combine(outputDirectory, "SecondSpawn.exe"),
+                target = BuildTarget.StandaloneWindows64,
+                options = buildOptions
+            };
+
+            var report = BuildPipeline.BuildPlayer(options);
+            if (report.summary.result != BuildResult.Succeeded)
+            {
+                throw new InvalidOperationException(
+                    $"Second Spawn Windows build failed: {report.summary.result} ({report.summary.totalErrors} errors)");
+            }
+
+            Debug.Log($"[SecondSpawnBuildUtility] Built {options.locationPathName} in {report.summary.totalTime.TotalSeconds:0.0}s.");
+        }
+
+        private static string[] EnabledBuildScenes()
+        {
+            var scenes = EditorBuildSettings.scenes
+                .Where(scene => scene.enabled)
+                .Select(scene => scene.path)
+                .Where(path => !string.IsNullOrWhiteSpace(path))
+                .ToArray();
+
+            return scenes.Length > 0 ? scenes : new[] { FallbackScenePath };
+        }
+
+        private static string RepoRoot()
+        {
+            var unityProjectRoot = Directory.GetParent(Application.dataPath)?.FullName;
+            var repoRoot = unityProjectRoot == null ? null : Directory.GetParent(unityProjectRoot)?.FullName;
+            if (string.IsNullOrWhiteSpace(repoRoot))
+            {
+                throw new InvalidOperationException("Unable to resolve repository root from Unity project path.");
+            }
+
+            return repoRoot;
+        }
+    }
+}
+#endif

docs/design/03-systems-index.md

@@ -37,7 +37,7 @@ This index enumerates every system the game needs, categorizes by Core/Gameplay/
 | 4 | Input system (Unity Input System) | Core | MVP | Prototype | - | Player Controller |
 | 5 | Zone scene management (1 zone vertical slice) | Core | MVP | Prototype | (TDD pending) | NetworkRunner |
 | 6 | Combat (ARPG action) | Gameplay | MVP | Not started | (TDD pending) | Player Controller, Networked state |
-| 7 | NPC dialogue and human-believable NPC agent model | Gameplay | MVP | Design | [13-human-believable-npc-agent-model.md](13-human-believable-npc-agent-model.md) | api.dos.ai model service (phase 2 ready), Profile persistence |
+| 7 | NPC dialogue and human-believable NPC agent model | Gameplay | MVP | Design | [13-human-believable-npc-agent-model.md](13-human-believable-npc-agent-model.md), [16-npc-society-multi-agent-architecture.md](16-npc-society-multi-agent-architecture.md), [21-permanent-npc-story-characteristics.md](21-permanent-npc-story-characteristics.md) | api.dos.ai model service (phase 2 ready), Profile persistence |
 | 8 | Quest system (linear, 3-5 quests slice scope) | Gameplay | VS | Not started | (TDD pending) | NPC dialogue, persistence |
 | 9 | Dungeon instance (1 dungeon, 1 boss) | Gameplay | VS | Not started | (TDD pending) | Combat, NPC dialogue, Photon |
 | 10 | Boss LLM dialogue (Convai grounded) | Gameplay | VS | Not started | (TDD pending) | NPC dialogue |

docs/design/12-game-design-document.md

@@ -134,13 +134,14 @@ SECOND SPAWN is not:
 
 ## 6. Setting and Tone
 
-SECOND SPAWN takes place in the MetaDOS universe around the 2050 era, after
-DOS Labs proved that human life-time, weapon testing, Hunters, and global
-spectacle could become one economy. This is not another MetaDOS battle royale.
-MetaDOS is the tournament layer of the same technology stack: humans enter AMB
-cocoons, control Hunter Frames, and compete for SECOND. SECOND SPAWN
-is what happens when that cocoon, Frame, agent-brain, and TIME economy stops
-being only spectacle and becomes the survival infrastructure of the real world.
+SECOND SPAWN takes place in the MetaDOS universe during the early Nibirium era,
+before DOS Labs turns human life-time, weapon testing, Hunters, and global
+spectacle into the public MetaDOS tournament economy. This is not another
+MetaDOS battle royale. MetaDOS is the later tournament layer of the same
+technology stack: humans enter AMB cocoons, control Hunter Frames, and compete
+for SECOND. SECOND SPAWN is what happens before that stack becomes polished
+spectacle, when cocoon, Frame, agent-brain, and TIME systems first become
+survival infrastructure in the real world.
 
 The world should feel readable, energetic, and progression-driven rather than
 overly bleak. The core audience is closer to fans of system, ranking,
@@ -212,12 +213,12 @@ This timeline is inherited from the MetaDOS GDD and adapted for SECOND SPAWN:
 
 | Year | Anchor | SECOND SPAWN Relevance |
 | ---- | ---- | ---- |
-| 2030 | A meteorite called Nibiru explodes in an airburst over Canada, changing the environment in the affected region. | The Nibiru event becomes the origin point for TIME research, disaster recovery, extraction, and corporate control. |
-| 2030s | DOS Labs becomes the only legitimate company able to manage and exploit Nibiru-derived material. | DOS Labs gains the leverage to reshape energy, biotech, warfare, and public policy. |
-| 2040 | DOS Labs discovers that Nibiru-derived material can sustain human life through AMB technology, using CT-like body scanning and an under-arm biological monitor that displays remaining life time. | TIME becomes a measurable life medium, and SECOND becomes the unit used to count it. |
-| 2040s | Avax wants the life-extension technology to broadly benefit humanity. Dr.J betrays him, monopolizes DOS Labs, and turns the corporation toward profit and influence. Avax survives and escapes with core technologies. | The world inherits a fracture between open survival technology and corporate life-time control. |
+| 2028 | A meteorite called Nibiru explodes in an airburst over Canada, changing the environment in the affected region. | The Nibiru event becomes the origin point for TIME research, disaster recovery, extraction, and corporate control. |
+| 2028-2030 | DOS Labs becomes the only legitimate company able to manage and exploit Nibiru-derived material. | DOS Labs gains the leverage to reshape energy, biotech, warfare, and public policy. |
+| 2030-2033 | DOS Labs discovers that Nibiru-derived material can sustain human life through early AMB technology, using CT-like body scanning and an under-arm biological monitor that displays remaining life time. | TIME becomes a measurable life medium, and SECOND becomes the unit used to count it. |
+| 2033-2038 | SECOND SPAWN demo era. Early Frames, BodyTime accounting, transfer anomalies, local Gates, and agent-assisted response teams appear in frontier wards. Avax wants the life-extension technology to broadly benefit humanity. Dr.J betrays him, monopolizes DOS Labs, and turns the corporation toward profit and influence. Avax survives and escapes with core technologies. | The world inherits a fracture between open survival technology and corporate life-time control. |
 | 2050 | DOS Labs creates MetaDOS, the Tournament of the Century, held every 4 years and watched globally. Players enter AMB cocoons and control Hunter Frames in a tournament layer where winners can receive prolonged life time, money, fame, or other resources. | MetaDOS normalizes SECOND as prize, currency, and measured life-time, while training Hunter Frames and agent brains through spectacle. |
-| After MetaDOS | SECOND SPAWN begins from the consequences of that system rather than repeating the tournament format. | The focus moves from cocoon-controlled tournament Frames to real-world Frames, reincarnation, AI agents, NPC societies, and contested zones. |
+| After MetaDOS | Later SECOND SPAWN eras can explore the consequences of that system rather than repeating the tournament format. | The focus can move from cocoon-controlled tournament Frames to real-world Frames, reincarnation, AI agents, NPC societies, and contested zones. |
 
 ### Key Lore Anchors
 
@@ -256,11 +257,11 @@ This timeline is inherited from the MetaDOS GDD and adapted for SECOND SPAWN:
 
 ### SECOND SPAWN Story Premise
 
-After MetaDOS, DOS Labs no longer only sells spectacle. It has shown the world
-that TIME can be measured, wagered, rewarded, and used to recruit the strongest
-survivors. SECOND SPAWN asks what happens when the same world pushes beyond
-cocoon play and lets Frames, including Hunter-derived combat Frames,
-become real-world survival infrastructure.
+In the early Nibirium era, DOS Labs has not yet sold MetaDOS as spectacle. It
+is learning that TIME can be measured, loaded, wagered, rewarded, and used to
+train the strongest survivors. SECOND SPAWN asks what happens before the
+tournament layer becomes public, when Frames, including early Hunter-derived
+combat Frames, first become real-world survival infrastructure.
 
 A Frame is not a character slot. It is a TIME-powered bio-synthetic human body
 with its own agent brain and capacity for a neural imprint. A human in an AMB
@@ -296,10 +297,11 @@ use these hooks:
 - Why TIME matters: The body's operating life is visible, limited, and measured
   in SECOND. TIME is both a survival medium and a tactical resource for
   services, recovery, access, or risk decisions.
-- What NPCs know: Hub NPCs understand that MetaDOS made life-time public and
-  valuable. Some remember DOS Labs propaganda, some distrust Frames,
-  some treat offline agents as workers, and some fear consciousness transfer as
-  identity theft.
+- What NPCs know: Hub NPCs understand that Nibirium, AMB trials, and DOS Labs
+  contracts are making life-time measurable and valuable. Some know MetaDOS
+  only as a rumor or internal program name, some distrust Frames, some treat
+  offline agents as workers, and some fear consciousness transfer as identity
+  theft.
 - Faction tension: DOS Labs loyalists, Avax-aligned technologists, independent
   Hunters, local settlement authorities, black-market body brokers, and
   self-directed AI/NPC communities can all want different rules for bodies,