settled-reach/content/global/knowledge/entity-attributes.yaml

# Entity Knowledge Attributes — 16 canonical keys
# Source: D-024 (10-axis model), wiki-review workshop A7, v01-content-scoping workshop
# All keys are observer->target, stored in EntityKnowledge.known_attributes BTreeMap<String, String>
# Reference: docs/wiki/knowledge/entity-attributes.md

# Categories: identity (4), social (2), behavioral (2), leverage (2), investigation (2), role-perspective (4)
# History: 14 original keys + 4 new role-perspective keys + 2 renames (secret_held -> leverage_held, secret_confidence -> leverage_confidence)

attributes:

  # --- Identity Attributes (4) ---

  - key: name
    category: identity
    value_type: freeform
    description: >
      Full name as known to the observer. If absent or generic,
      monologue and dialogue use role descriptor instead.
    examples:
      - "Kael Davan"
      - "Kael"
      - "the dock worker"

  - key: role
    category: identity
    value_type: freeform
    description: >
      Occupational or social role. Default descriptor when name is unknown.
      Used in access tier calculation.
    examples:
      - "dock worker"
      - "shift supervisor"
      - "bartender"
      - "ring coordinator"

  - key: faction
    category: identity
    value_type: freeform
    description: >
      Institutional or organizational allegiance. Commission-tagged individuals
      trigger different NPC behavior. Used for authority/peer dialogue filtering.
    examples:
      - "Commission"
      - "civilian"
      - "ring member"
      - "unknown"

  - key: species
    category: identity
    value_type: freeform
    description: >
      Species identifier. Not load-bearing in v0.1 (all human).
      Placeholder for future non-human NPCs.
    examples:
      - "human"

  # --- Social Attributes (2) ---

  - key: relationship_type
    category: social
    value_type: freeform
    description: >
      Relationship category from observer's perspective.
      Drives RelationshipState calculation and monologue emotional tone.
    examples:
      - "colleague"
      - "friend"
      - "authority figure"
      - "suspect"
      - "partner"
      - "stranger"

  - key: trust_level
    category: social
    value_type: enum
    values:
      - trusted
      - reliable
      - uncertain
      - suspicious
      - compromised
    description: >
      Trust assessment — observer's subjective judgment. Encompasses both the
      read action and the state. No separate trust_read key. Gates trust-tier
      dialogue (surface/real/secret).

  # --- Behavioral Attributes (2) ---

  - key: routine_pattern
    category: behavioral
    value_type: freeform
    description: >
      Observed routine description. Deviation detection triggers monologue
      when current behavior doesn't match known pattern.
    examples:
      - "morning shift 06:00-14:00, bar after shift"
      - "arrives 06:00, break 10:30, departs 14:00"
      - "irregular schedule, seen at odd hours"

  - key: behavior_flags
    category: behavioral
    value_type: freeform
    description: >
      Comma-separated behavioral observations. Multiple flags accumulate
      as evidence. Detective's analytical lattice auto-flags some behaviors.
    examples:
      - "nervous,lattice_checking"
      - "avoidance_pattern,evasive"
      - "spending_beyond_means"
      - "reliable,punctual"

  # --- Leverage Attributes (2) ---
  # Renamed from secret_held/secret_confidence per workshop A7

  - key: leverage_held
    category: leverage
    value_type: freeform
    renamed_from: secret_held
    description: >
      What the observer believes gives them power over this entity.
      Covers secrets, debts, promises, obligations, and compromising positions.
      Drives PersonOfInterest state. Gates confrontation dialogue.
    examples:
      - "ring membership"
      - "unreported evidence"
      - "gambling debt"
      - "exit attempt"
      - "owes favor to Voss"

  - key: leverage_confidence
    category: leverage
    value_type: enum
    renamed_from: secret_confidence
    values:
      - suspected
      - likely
      - confirmed
    description: >
      How certain the observer is about the leverage. Suspected allows
      fishing questions; confirmed enables direct confrontation.

  # --- Investigation Attributes (2) ---

  - key: tell_observed
    category: investigation
    value_type: freeform
    description: >
      Specific tell noted by observer. Captures the observer's interpretive
      conclusion about behavior. Accumulated tells build case strength.
      Monologue references specific tells when they recur.
    examples:
      - "looks left when lying"
      - "leaves when Torek arrives"
      - "checks lattice before answering"
      - "forced casualness after shift supervisor passes"
    implementation_note: >
      Server may track tells via behavior_flags internally. tell_observed is
      retained as a content-authoring key for its distinct narrative purpose.

  - key: contradiction_flagged
    category: investigation
    value_type: freeform
    description: >
      Boolean-ish flag — presence of value means contradiction detected.
      THE FRIEND arc trigger. When set, monologue tone shifts, dialogue
      options change, RelationshipState moves toward PersonOfInterest.
    examples:
      - "meeting_unknown_contact"
      - "avoidance_inconsistency"
      - "manifest_access_mismatch"
    implementation_note: >
      Server may track via behavior_flags with contradiction: prefix.
      Retained as documented key for arc transition gating.

  # --- Role-Perspective Attributes (4 new per workshop A7) ---
  # Same enums across all archetypes; interpretation is archetype-dependent.
  # Smuggler reads "risk" as operational exposure; detective reads it as
  # threat to investigation. See wiki entity-attributes.md for full mapping.

  - key: risk_assessment
    category: role-perspective
    value_type: enum
    values:
      - none
      - low
      - moderate
      - high
      - critical
    description: >
      Observer's assessment of how much danger this entity poses or attracts.
      Gates operational monologue. High-risk triggers cautionary dialogue.
      Nature of "risk" depends on observer archetype.

  - key: loyalty_assessment
    category: role-perspective
    value_type: enum
    values:
      - solid
      - dependable
      - uncertain
      - wavering
      - hostile
    description: >
      Observer's assessment of this entity's reliability and loyalty.
      Determines how much the observer relies on or confides in the target.
      Wavering triggers monitoring; hostile triggers defensive posture.

  - key: position_integrity
    category: role-perspective
    value_type: enum
    values:
      - solid
      - thin
      - cracking
      - blown
      - "N/A"
    description: >
      Observer's assessment of this entity's cover, position stability,
      or facade status. When degraded, monologue reflects increasing anxiety
      or strategic recalculation. N/A when cover concept does not apply.

  - key: moral_weight
    category: role-perspective
    value_type: enum
    values:
      - innocent
      - peripheral
      - complicit
      - compromised
      - willing
    description: >
      Observer's assessment of this entity's moral involvement. Shapes the
      observer's moral arc and internal conflict. Smuggler assesses complicity
      in ring operations; detective assesses culpability in the crime.
      Same scale, different lens.