14 files changed, 64 insertions, 84 deletions
diff --git a/engine/entities/base.ts b/engine/entities/base.ts
index 84b9acf..c1cf6d8 100644
--- a/engine/entities/base.ts
+++ b/engine/entities/base.ts
@@ -4,7 +4,6 @@ import type { Brand } from '@hollowdark/utils/types/brand'
 /**
  * Branded IDs — string at runtime, distinct at compile time so a PersonId
  * can't silently flow into a slot that expects a RelationshipId.
- * (utils/types/brand.ts)
  */
 export type PersonId = Brand<string, 'PersonId'>
 export type RelationshipId = Brand<string, 'RelationshipId'>
@@ -26,7 +25,6 @@ export type EntityKind = 'person' | 'relationship' | 'institution' | 'place' | '
  * their specific id/kind pair — `Person extends BaseEntity<PersonId, 'person'>`.
  * `deterministicSeed` powers lazy Tier 3 regeneration: given the seed, the
  * entity's trajectory is fully reproducible without persisted state.
- * (ARCHITECTURE.md §26)
  */
 export interface BaseEntity<Id extends string = string, K extends EntityKind = EntityKind> {
   readonly id: Id
diff --git a/engine/entities/event-log-entry.ts b/engine/entities/event-log-entry.ts
index f31536d..1e107f4 100644
--- a/engine/entities/event-log-entry.ts
+++ b/engine/entities/event-log-entry.ts
@@ -1,5 +1,5 @@
 import type { GameTime } from '@hollowdark/time/gameTime'
-import type { EventLogEntryId, PersonId } from './base'
+import type { EventLogEntryId, PersonId } from '@hollowdark/engine/entities/base'
 
 /**
  * Consequences logged against a specific event resolution. The shape is
diff --git a/engine/entities/flow-entry.ts b/engine/entities/flow-entry.ts
index bd781d5..ba2b11a 100644
--- a/engine/entities/flow-entry.ts
+++ b/engine/entities/flow-entry.ts
@@ -1,5 +1,5 @@
 import type { GameTime } from '@hollowdark/time/gameTime'
-import type { FlowEntryId, PersonId, PlaceId, WorldEventId } from './base'
+import type { FlowEntryId, PersonId, PlaceId, WorldEventId } from '@hollowdark/engine/entities/base'
 
 /**
  * A compact snapshot of the context that produced a flow passage. Kept
diff --git a/engine/entities/institution.ts b/engine/entities/institution.ts
index 4b3c050..d89aac2 100644
--- a/engine/entities/institution.ts
+++ b/engine/entities/institution.ts
@@ -1,6 +1,6 @@
 import type { GameTime } from '@hollowdark/time/gameTime'
-import type { BaseEntity, InstitutionId, PersonId, PlaceId } from './base'
-import type { CultureDescriptor } from './place'
+import type { BaseEntity, InstitutionId, PersonId, PlaceId } from '@hollowdark/engine/entities/base'
+import type { CultureDescriptor } from '@hollowdark/engine/entities/place'
 
 export type InstitutionType =
   | 'company'
diff --git a/engine/entities/memoir.ts b/engine/entities/memoir.ts
index c0f44f3..1f3f37f 100644
--- a/engine/entities/memoir.ts
+++ b/engine/entities/memoir.ts
@@ -1,5 +1,5 @@
 import type { GameTime } from '@hollowdark/time/gameTime'
-import type { EventLogEntryId, MemoirId, PersonId } from './base'
+import type { EventLogEntryId, MemoirId, PersonId } from '@hollowdark/engine/entities/base'
 
 export interface MemoirChapter {
   readonly order: number
@@ -12,9 +12,10 @@ export interface MemoirChapter {
 }
 
 /**
- * Generated at character death. 15,000–30,000 words, 8–15 chapters. Persists
- * forever in the world's archive; descendants may find it on the Memoirs
- * shelf or referenced in flow (docs/14-memoirs.md, ARCHITECTURE.md §17).
+ * A character's generated life story. Produced at death, 15,000–30,000
+ * words across 8–15 chapters. Persists forever in the world's archive;
+ * descendants may find it on the Memoirs shelf or see it referenced in
+ * their own flow.
  */
 export interface Memoir {
   readonly id: MemoirId
diff --git a/engine/entities/person-name.ts b/engine/entities/person-name.ts
index 5f84b41..8c234dc 100644
--- a/engine/entities/person-name.ts
+++ b/engine/entities/person-name.ts
@@ -1,8 +1,8 @@
 /**
  * A character's name as tracked by the simulation. Surnames follow
- * inheritance rules per region/era (docs/19-names.md) — including keep-
- * maiden, hyphenate, matrilineal, and ad-hoc changes — so the structure
- * preserves both the current surname and the maiden form when relevant.
+ * inheritance rules per region and era — including keep-maiden, hyphenate,
+ * matrilineal, and ad-hoc changes — so the structure preserves both the
+ * current surname and the maiden form when relevant.
  */
 export interface PersonName {
   readonly given: string
diff --git a/engine/entities/person.ts b/engine/entities/person.ts
index beabede..1dc28a1 100644
--- a/engine/entities/person.ts
+++ b/engine/entities/person.ts
@@ -1,26 +1,26 @@
 import type { GameTime } from '@hollowdark/time/gameTime'
-import type { CareerState } from '../career/career'
-import type { EconomicState } from '../economics/economic'
-import type { Condition, HealthState } from '../health/health'
-import type { MentalHealthState } from '../health/mental-health'
-import type { Dependency } from '../state/dependency'
-import type { MoodState } from '../state/mood'
-import type { SatisfactionProfile } from '../state/satisfaction'
-import type { Scar } from '../state/scar'
-import type { AttachmentDistribution } from '../traits/attachment'
-import type { BigFiveProfile } from '../traits/big-five'
-import type { CoreBeliefs } from '../traits/core-beliefs'
-import type { DarkTriadProfile } from '../traits/dark-triad'
-import type { SexualOrientation } from '../traits/orientation'
-import type { ValuesOrientation } from '../traits/values'
-import type { BaseEntity, PersonId, PlaceId, RelationshipId } from './base'
-import type { EventLogEntry } from './event-log-entry'
-import type { PersonName } from './person-name'
-import type { ReputationProfile } from './reputation'
-import type { ResidenceEntry } from './residence'
-import type { StatusDescriptor } from './status'
-
-/** Modes of death per docs/20-death-textures.md. */
+import type { CareerState } from '@hollowdark/engine/career/career'
+import type { EconomicState } from '@hollowdark/engine/economics/economic'
+import type { Condition, HealthState } from '@hollowdark/engine/health/health'
+import type { MentalHealthState } from '@hollowdark/engine/health/mental-health'
+import type { Dependency } from '@hollowdark/engine/state/dependency'
+import type { MoodState } from '@hollowdark/engine/state/mood'
+import type { SatisfactionProfile } from '@hollowdark/engine/state/satisfaction'
+import type { Scar } from '@hollowdark/engine/state/scar'
+import type { AttachmentDistribution } from '@hollowdark/engine/traits/attachment'
+import type { BigFiveProfile } from '@hollowdark/engine/traits/big-five'
+import type { CoreBeliefs } from '@hollowdark/engine/traits/core-beliefs'
+import type { DarkTriadProfile } from '@hollowdark/engine/traits/dark-triad'
+import type { SexualOrientation } from '@hollowdark/engine/traits/orientation'
+import type { ValuesOrientation } from '@hollowdark/engine/traits/values'
+import type { BaseEntity, PersonId, PlaceId, RelationshipId } from '@hollowdark/engine/entities/base'
+import type { EventLogEntry } from '@hollowdark/engine/entities/event-log-entry'
+import type { PersonName } from '@hollowdark/engine/entities/person-name'
+import type { ReputationProfile } from '@hollowdark/engine/entities/reputation'
+import type { ResidenceEntry } from '@hollowdark/engine/entities/residence'
+import type { StatusDescriptor } from '@hollowdark/engine/entities/status'
+
+/** The ten modes of death the simulation can resolve. */
 export type DeathMode =
   | 'expected_old_age'
   | 'sudden_accident'
@@ -35,7 +35,7 @@ export type DeathMode =
 /**
  * The defining demographic facts of a birth, captured in prose-ready form.
  * The familyContext string is the one-paragraph summary the opening scene
- * draws on (docs/17-first-hour.md §"Birth moment").
+ * draws on.
  */
 export interface BirthRecord {
   readonly date: GameTime
@@ -51,15 +51,15 @@ export interface DeathRecord {
 }
 
 /**
- * NPC simulation fidelity tier. 1 = full weekly simulation (~10-30 entities),
- * 2 = quarterly compressed, 3 = generated on demand from seed.
- * See docs/06-autonomy.md §"Tiered simulation fidelity".
+ * NPC simulation fidelity tier. 1 = full weekly simulation (~10–30
+ * close-orbit entities), 2 = quarterly compressed (dormant relatives,
+ * drifted friends), 3 = generated on demand from seed (everyone else).
  */
 export type SimulationTier = 1 | 2 | 3
 
 /**
  * Person — the main simulated entity. Players and NPCs share this shape.
- * Fields are grouped by trait layer (docs/04-traits.md):
+ * Fields are grouped by trait layer:
  *
  *   Layer 1  temperament (Big Five + Dark Triad) — mostly stable
  *   Layer 2  developmental (attachment, core beliefs, values, orientation)
@@ -75,65 +75,52 @@ export interface Person extends BaseEntity<PersonId, 'person'> {
   readonly birth: BirthRecord
   readonly death: DeathRecord | null
 
-  // Layer 1 — temperament
   readonly bigFive: BigFiveProfile
   readonly darkTriad: DarkTriadProfile
 
-  // Layer 2 — developmental
   readonly attachment: AttachmentDistribution
   readonly coreBeliefs: CoreBeliefs
   readonly conscienceCapacity: number
   readonly values: ValuesOrientation
   readonly orientation: SexualOrientation
 
-  // Layer 3 — fluctuating state
   readonly mood: MoodState
   readonly stress: number
   readonly energy: number
   readonly traumaLoad: number
   readonly satisfaction: SatisfactionProfile
 
-  // Layer 4 — acquired
   readonly skills: ReadonlyMap<string, number>
   readonly knowledge: ReadonlyMap<string, number>
   readonly habits: readonly string[]
   readonly dependencies: readonly Dependency[]
   readonly scars: readonly Scar[]
 
-  // Layer 5 — social
   readonly reputation: ReputationProfile
   readonly status: StatusDescriptor
   readonly networkCapital: number
 
-  // Health
   readonly health: HealthState
   readonly chronicConditions: readonly Condition[]
   readonly mentalHealthState: MentalHealthState
 
-  // Economic / career
   readonly economic: EconomicState
   readonly career: CareerState
 
-  // Relationships + location
   readonly relationshipIds: readonly RelationshipId[]
   readonly currentPlaceId: PlaceId
   readonly residenceHistory: readonly ResidenceEntry[]
 
-  // Simulation metadata
   readonly tier: SimulationTier
   readonly lastSimulatedAt: GameTime
 
-  // Event history
   readonly eventLog: readonly EventLogEntry[]
   readonly memorableMoments: readonly string[]
 
-  // Player-character flags
   readonly isPlayerCharacter: boolean
   readonly playerCharacterStartedAt: GameTime | null
   readonly playerCharacterEndedAt: GameTime | null
 
-  // Family (denormalised for fast access; the authoritative source is the
-  // Relationship entities keyed family_parent / family_child / family_spouse)
   readonly parentIds: readonly [PersonId | null, PersonId | null]
   readonly childIds: readonly PersonId[]
   readonly spouseIds: readonly PersonId[]
diff --git a/engine/entities/place.ts b/engine/entities/place.ts
index 2a38c41..8ec1f9b 100644
--- a/engine/entities/place.ts
+++ b/engine/entities/place.ts
@@ -1,4 +1,4 @@
-import type { BaseEntity, PersonId, PlaceId } from './base'
+import type { BaseEntity, PersonId, PlaceId } from '@hollowdark/engine/entities/base'
 
 export type PlaceType = 'region' | 'city' | 'neighborhood' | 'specific_location'
 
@@ -40,7 +40,6 @@ export interface Place extends BaseEntity<PlaceId, 'place'> {
   readonly type: PlaceType
   readonly parentPlaceId: PlaceId | null
 
-  // Present for regions and cities; null for specific locations.
   readonly culture: CultureDescriptor | null
   readonly climate: ClimateDescriptor | null
   readonly economy: EconomicCharacter | null
@@ -48,7 +47,6 @@ export interface Place extends BaseEntity<PlaceId, 'place'> {
 
   readonly population: number
 
-  // Present for specific locations (houses, workplaces); null for containers.
   readonly ownerId: PersonId | null
   readonly currentResidents: readonly PersonId[]
   readonly propertyValue: number | null
diff --git a/engine/entities/relationship.ts b/engine/entities/relationship.ts
index ec00007..2a7710b 100644
--- a/engine/entities/relationship.ts
+++ b/engine/entities/relationship.ts
@@ -1,5 +1,5 @@
 import type { GameTime } from '@hollowdark/time/gameTime'
-import type { BaseEntity, PersonId, RelationshipId } from './base'
+import type { BaseEntity, PersonId, RelationshipId } from '@hollowdark/engine/entities/base'
 
 export type RelationType =
   | 'family_parent'
@@ -30,10 +30,9 @@ export type RelationType =
 export type RelationshipState = 'warm' | 'neutral' | 'strained' | 'ruptured' | 'dormant'
 
 /**
- * The four axes of intimacy (docs/07-relationships.md §"Relationship state
- * vector"). Each 0–1. Tracked separately because a marriage can be high
- * on practical and low on emotional — that's a specific life texture, not
- * a compatibility score.
+ * The four axes of intimacy. Each 0–1. Tracked separately because a
+ * marriage can be high on practical and low on emotional — that's a
+ * specific life texture, not a compatibility score.
  */
 export interface IntimacyAxes {
   readonly emotional: number
@@ -88,9 +87,9 @@ export interface LoveLanguageMatrix {
 }
 
 /**
- * Asymmetric perception: A and B each have their own mental model of the
- * relationship. Large asymmetries fire scenes (confession, rebuff, shocked
- * realisation). See docs/07-relationships.md §"Asymmetric perception".
+ * Asymmetric perception: A and B each carry their own mental model of the
+ * relationship. Large asymmetries fire scenes — confession, rebuff,
+ * shocked realisation.
  */
 export interface RelationshipPerception {
   readonly perceivedType: RelationType
@@ -162,15 +161,12 @@ export interface Relationship extends BaseEntity<RelationshipId, 'relationship'>
   readonly lastInteractionAt: GameTime
   readonly interactionFrequency: number
 
-  // Romantic-only details; null when the relationship isn't romantic.
   readonly romanticPhase: RomanticPhase | null
   readonly sexualActivity: SexualActivityState | null
   readonly infidelityHistory: readonly InfidelityEvent[]
   readonly commitmentLevel: number
 
-  // Family-only.
   readonly familyRelationType: FamilyRelation | null
 
-  // Professional-only.
   readonly workRelationType: WorkRelation | null
 }
diff --git a/engine/entities/residence.ts b/engine/entities/residence.ts
index a052c42..83ddce8 100644
--- a/engine/entities/residence.ts
+++ b/engine/entities/residence.ts
@@ -1,5 +1,5 @@
 import type { GameTime } from '@hollowdark/time/gameTime'
-import type { PlaceId } from './base'
+import type { PlaceId } from '@hollowdark/engine/entities/base'
 
 /** A span of time a character lived at a specific place. Open-ended if the
  *  character still lives there. */
diff --git a/engine/entities/routine.ts b/engine/entities/routine.ts
index 251cbde..a7068c1 100644
--- a/engine/entities/routine.ts
+++ b/engine/entities/routine.ts
@@ -1,5 +1,5 @@
 import type { GameTime } from '@hollowdark/time/gameTime'
-import type { PersonId, RoutineId } from './base'
+import type { PersonId, RoutineId } from '@hollowdark/engine/entities/base'
 
 export type RoutineCategory = 'work' | 'relationships' | 'self' | 'home' | 'play' | 'service'
 
@@ -27,7 +27,7 @@ export interface RoutineItem {
 /**
  * Persistent weekly commitments for a character. Routines run silently in
  * the flow stream — the player sets them once, they keep running until
- * changed (docs/05-time-system.md §"Routines and flow").
+ * changed.
  */
 export interface Routine {
   readonly id: RoutineId
diff --git a/engine/entities/scheduled-event.ts b/engine/entities/scheduled-event.ts
index 08be670..254e979 100644
--- a/engine/entities/scheduled-event.ts
+++ b/engine/entities/scheduled-event.ts
@@ -1,10 +1,10 @@
 import type { GameTime } from '@hollowdark/time/gameTime'
-import type { PersonId, ScheduledEventId } from './base'
+import type { PersonId, ScheduledEventId } from '@hollowdark/engine/entities/base'
 
 /**
  * A future event trigger, either at a fixed time or when conditions hold.
  * Taking a bribe at 30 might schedule a `bribery_audit` at +15 years with
- * elevated weight (ARCHITECTURE.md §6 §"Scheduled events").
+ * elevated weight.
  */
 export interface ConditionalTrigger {
   readonly kind: 'conditional'
diff --git a/engine/entities/world-event.ts b/engine/entities/world-event.ts
index 8b4e2a6..ca158cc 100644
--- a/engine/entities/world-event.ts
+++ b/engine/entities/world-event.ts
@@ -1,5 +1,5 @@
 import type { GameTime } from '@hollowdark/time/gameTime'
-import type { BaseEntity, PersonId, PlaceId, WorldEventId } from './base'
+import type { BaseEntity, PersonId, PlaceId, WorldEventId } from '@hollowdark/engine/entities/base'
 
 export type EventCategory =
   | 'pandemic'
@@ -17,8 +17,8 @@ export type EventCategory =
 export type SeverityLevel = 'mild' | 'moderate' | 'severe' | 'catastrophic'
 
 /**
- * A named macro event decorating the timeline. See docs/02-world-events.md.
- * The character-level impact of each event is applied per-person via
+ * A named macro event decorating the timeline — a pandemic, war, cultural
+ * shift, economic crash. Character-level impact is applied per-person via
  * templates referenced by contentRef; this entity is the world-scale record.
  */
 export interface WorldEvent extends BaseEntity<WorldEventId, 'world_event'> {
diff --git a/engine/entities/world.ts b/engine/entities/world.ts
index 920fe05..8d0b328 100644
--- a/engine/entities/world.ts
+++ b/engine/entities/world.ts
@@ -1,11 +1,11 @@
 import type { GameTime } from '@hollowdark/time/gameTime'
-import type { PersonId, PlaceId, WorldEventId, WorldId } from './base'
-import type { ScheduledEvent } from './scheduled-event'
+import type { PersonId, PlaceId, WorldEventId, WorldId } from '@hollowdark/engine/entities/base'
+import type { ScheduledEvent } from '@hollowdark/engine/entities/scheduled-event'
 
 /**
- * Macro economic state tracked at the world scale. Individual characters'
- * economics are derived against this background (docs/09-economy.md
- * §"Macro economy").
+ * Macro economic state tracked at the world scale — inflation, employment,
+ * market index, recession depth. Individual characters' economics derive
+ * against this background.
  */
 export interface MacroEconomicState {
   readonly inflationAnnual: number
@@ -33,14 +33,14 @@ export interface CrisisState {
 }
 
 /**
- * The world container. One continuous world per player (ARCHITECTURE.md §16,
- * docs/16-world-continuity.md). Time in this world never resets once
- * created; successive player characters advance it forward.
+ * The world container. One continuous world per player. Time in this world
+ * never resets once created; successive player characters advance it forward.
+ * `createdAt` is a real-world ISO timestamp, not a `GameTime`.
  */
 export interface World {
   readonly id: WorldId
   readonly seed: string
-  readonly createdAt: string // ISO timestamp, real-world clock — not a GameTime
+  readonly createdAt: string
 
   readonly currentGameTime: GameTime