Migrate remaining relative imports to @hollowdark/*; strip //-comments and doc references, JSDoc-only

28 files changed, 92 insertions, 113 deletions

diff --git a/engine/career/career.ts b/engine/career/career.ts
index aa19584..e8a5af2 100644
--- a/engine/career/career.ts
+++ b/engine/career/career.ts
@@ -1,5 +1,5 @@
 import type { GameTime } from '@hollowdark/time/gameTime'
-import type { InstitutionId } from '../entities/base'
+import type { InstitutionId } from '@hollowdark/engine/entities/base'
 
 export type CareerTrajectory = 'rising' | 'steady' | 'declining' | 'stalled'
 
diff --git a/engine/economics/affordability.ts b/engine/economics/affordability.ts
index ef57d3f..827ccd8 100644
--- a/engine/economics/affordability.ts
+++ b/engine/economics/affordability.ts
@@ -1,8 +1,7 @@
 /**
  * The "What you could afford" surface on the Money screen. Hidden numbers
  * resolve into qualitative feasibility labels so the player answers
- * "can I afford this?" without ever seeing a number (docs/09-economy.md
- * §"The 'What you could afford' design").
+ * "can I afford this?" without ever seeing a number.
  */
 export type Feasibility =
   | 'comfortable'
diff --git a/engine/economics/economic.ts b/engine/economics/economic.ts
index 1197cde..2d37ced 100644
--- a/engine/economics/economic.ts
+++ b/engine/economics/economic.ts
@@ -1,9 +1,8 @@
 /**
- * Economic state. All numbers in "marks" (the world's universal currency).
- * The player never sees any of these — they surface as prose and qualitative
- * affordability context (docs/09-economy.md, ARCHITECTURE.md §14).
+ * A coarse wealth tier derived from the hidden economic state. Never
+ * displayed numerically; informs surface prose ("struggling", "comfortable",
+ * "old money").
  */
-
 export type EconomicClass =
   | 'destitute'
   | 'struggling'
@@ -44,6 +43,11 @@ export interface Debt {
   readonly apr: number
 }
 
+/**
+ * Hidden economic state for a character. All numbers are in "marks" (the
+ * world's universal currency). Never surfaced to the player as digits —
+ * the simulation drives prose and qualitative affordability context.
+ */
 export interface EconomicState {
   readonly cashOnHand: number
   readonly accounts: readonly Account[]
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
 
diff --git a/engine/health/health.ts b/engine/health/health.ts
index e08433d..4c69d34 100644
--- a/engine/health/health.ts
+++ b/engine/health/health.ts
@@ -41,10 +41,9 @@ export interface Condition {
 }
 
 /**
- * A condition the simulation tracks but the character doesn't yet know about.
- * Surface paths include worsening symptoms, doctor visits, routine screens,
- * or incidental discovery (docs/08-mental-health.md §"Suicide risk" for the
- * comparable mental-health pattern; this covers physical equivalents).
+ * A condition the simulation tracks but the character doesn't yet know
+ * about. Surface paths include worsening symptoms, doctor visits, routine
+ * screens, or incidental discovery.
  */
 export interface UndiagnosedCondition {
   readonly id: string
diff --git a/engine/health/mental-health.ts b/engine/health/mental-health.ts
index 7130177..2e54e71 100644
--- a/engine/health/mental-health.ts
+++ b/engine/health/mental-health.ts
@@ -48,7 +48,7 @@ export interface Medication {
 
 /**
  * Hidden even from the character until crisis. The simulation knows; the
- * prose surfaces behaviour, not numbers (docs/08-mental-health.md §"Suicide").
+ * prose surfaces behaviour, never numbers.
  */
 export interface SuicidalRisk {
   readonly current: number
diff --git a/engine/state/dependency.ts b/engine/state/dependency.ts
index 47787da..e3aca72 100644
--- a/engine/state/dependency.ts
+++ b/engine/state/dependency.ts
@@ -1,8 +1,7 @@
 import type { GameTime } from '@hollowdark/time/gameTime'
 
 /**
- * A substance or behavioural dependency at a given stage of progression.
- * Stages mirror docs/08-mental-health.md §"Addiction modeled honestly":
+ * A substance or behavioural dependency at a given stage of progression:
  * experimentation → regular use → problem use → dependence → crisis →
  * recovery | chronic | death.
  */
diff --git a/engine/state/mood.ts b/engine/state/mood.ts
index 501a699..205b5ec 100644
--- a/engine/state/mood.ts
+++ b/engine/state/mood.ts
@@ -4,7 +4,6 @@ import type { GameTime } from '@hollowdark/time/gameTime'
  * Current-week emotional state on the valence × arousal plane.
  *   valence   -1 (negative) to +1 (positive)
  *   arousal   -1 (calm) to +1 (activated)
- * See docs/08-mental-health.md §"Separate variables".
  */
 export interface MoodState {
   readonly valence: number
diff --git a/engine/state/satisfaction.ts b/engine/state/satisfaction.ts
index a10421b..eae65ec 100644
--- a/engine/state/satisfaction.ts
+++ b/engine/state/satisfaction.ts
@@ -1,8 +1,7 @@
 /**
  * Life satisfaction split into hedonic (day-to-day pleasure) and eudaimonic
- * (sense of meaning / purpose). They can diverge, and eudaimonic matters
- * more for end-of-life peace (docs/13-spirituality.md §"Life satisfaction
- * is distinct from happiness"). Each 0–1.
+ * (sense of meaning / purpose). They can diverge; eudaimonic matters more
+ * for end-of-life peace. Each 0–1.
  */
 export interface SatisfactionProfile {
   readonly hedonic: number
diff --git a/engine/traits/attachment.ts b/engine/traits/attachment.ts
index 7af4c1b..eae77fa 100644
--- a/engine/traits/attachment.ts
+++ b/engine/traits/attachment.ts
@@ -1,7 +1,7 @@
 /**
  * Attachment is tracked as a distribution, not a single tag. Fractions sum
  * to 1.0; a character is rarely purely one style. Set by age 3 based on
- * caregiver behaviour, mostly fixed thereafter (docs/04-traits.md §"Layer 2").
+ * caregiver behaviour, mostly fixed thereafter.
  */
 export interface AttachmentDistribution {
   readonly secure: number
diff --git a/engine/traits/big-five.ts b/engine/traits/big-five.ts
index 425c91c..dbf5bd7 100644
--- a/engine/traits/big-five.ts
+++ b/engine/traits/big-five.ts
@@ -1,6 +1,6 @@
 /**
- * Big Five temperament profile, each 0–100. Mostly stable across a life
- * with slow drift under sustained conditions. See docs/04-traits.md §"Layer 1".
+ * Big Five temperament profile. Each axis is 0–100, mostly stable across
+ * a life with slow drift under sustained conditions.
  */
 export interface BigFiveProfile {
   readonly openness: number
diff --git a/engine/traits/core-beliefs.ts b/engine/traits/core-beliefs.ts
index 4e3b85a..f35daa0 100644
--- a/engine/traits/core-beliefs.ts
+++ b/engine/traits/core-beliefs.ts
@@ -1,6 +1,6 @@
 /**
- * Core beliefs shape how adult events are interpreted (docs/04-traits.md
- * §"Layer 2"). Each 0–100. Formed in early childhood, harder to shift after.
+ * Core beliefs shape how adult events are interpreted. Each axis is 0–100,
+ * formed in early childhood and harder to shift after.
  */
 export interface CoreBeliefs {
   readonly selfWorth: number
diff --git a/engine/traits/dark-triad.ts b/engine/traits/dark-triad.ts
index e8e1450..fff49c5 100644
--- a/engine/traits/dark-triad.ts
+++ b/engine/traits/dark-triad.ts
@@ -1,7 +1,7 @@
 /**
- * Dark Triad profile, each 0–100. Distribution is skewed low — most
- * characters sit in the 20–40 range; a small minority above 60 drives
- * specific life shapes (docs/04-traits.md §"Dark Triad characters in play").
+ * Dark Triad profile. Each axis is 0–100. Distribution in the simulation
+ * skews low — most characters sit in the 20–40 range; a small minority
+ * above 60 drives specific life shapes.
  */
 export interface DarkTriadProfile {
   readonly narcissism: number
diff --git a/engine/traits/orientation.ts b/engine/traits/orientation.ts
index 60decd9..e72a9cf 100644
--- a/engine/traits/orientation.ts
+++ b/engine/traits/orientation.ts
@@ -1,6 +1,6 @@
 /**
  * Gender identity and sexual orientation. Continuous axes plus a discrete
- * gender tag. See docs/04-traits.md §"Layer 2" and docs/10-sexuality.md.
+ * gender tag.
  *
  *   sexualAttraction   0 = hetero-exclusive, 100 = homo-exclusive
  *   romanticAttraction independent continuous axis
diff --git a/engine/traits/values.ts b/engine/traits/values.ts
index 0d67d16..83ae529 100644
--- a/engine/traits/values.ts
+++ b/engine/traits/values.ts
@@ -1,7 +1,7 @@
 /**
  * Values orientation. Each axis is 0–100 where 0 anchors the left-named
- * pole and 100 the right (e.g., tradition_vs_novelty: 0 = deeply traditional,
- * 100 = novelty-seeking). See docs/04-traits.md §"Layer 2".
+ * pole and 100 the right (e.g., `tradition_vs_novelty`: 0 = deeply
+ * traditional, 100 = novelty-seeking).
  */
 export interface ValuesOrientation {
   readonly tradition_vs_novelty: number