# Client Knowledge Base — Profile Schema

The client KB is a living document. It starts with what the firm knows on day one and grows with every matter, every communication, every document, and every interaction. The goal is that when a returning client's name appears, the attorney already knows everything relevant — without digging.

---

## Profile Layers

### Layer 1 — Static Identity
Facts that don't change (or rarely change). Captured at client onboarding.

**Individual**
```typescript
interface IndividualIdentity {
  full_name_th: string;           // Thai script
  full_name_en: string;
  id_number: string;              // Thai national ID or passport number
  nationality: string;
  date_of_birth: string;
  occupation: string;
  employer?: string;

  // Contact
  email: string;
  phone: string;
  line_id?: string;
  preferred_language: 'th' | 'en' | string;
  preferred_channel: 'line' | 'email' | 'phone';

  // Family
  marital_status: 'single' | 'married' | 'divorced' | 'widowed';
  spouse_name?: string;
  spouse_contact?: string;
  property_regime?: 'sin_suan_tua' | 'sin_somros'; // personal vs marital property
  children: number;

  // Decision makers — who else influences or must approve decisions
  decision_influencers: {
    name: string;
    relationship: string;   // "spouse", "father", "business partner"
    involvement: 'must_approve' | 'usually_consulted' | 'cc_only';
  }[];
}
```

**Corporate**
```typescript
interface CorporateIdentity {
  company_name_th: string;
  company_name_en: string;
  registration_number: string;      // DBD registration
  registered_address: string;
  business_type: string;
  industry: string;
  registered_capital: number;       // THB

  // Key people
  primary_contact: string;          // contact_id
  primary_contact_role: string;
  authorized_signatories: string[];
  directors: DirectorRecord[];
  shareholders: ShareholderRecord[];

  // Group structure
  parent_company?: string;
  subsidiaries: string[];
  foreign_principal?: string;       // if a foreign company instructing Thai counsel

  // Decision makers
  decision_influencers: {
    name: string;
    role: string;
    involvement: 'must_approve' | 'usually_consulted' | 'cc_only';
  }[];
}
```

---

### Layer 2 — Asset Profile
Captured at onboarding, updated as matters reveal or change assets.

```typescript
interface AssetProfile {
  real_property: {
    chanote_number?: string;
    location: string;
    type: 'land' | 'condo' | 'house' | 'commercial';
    encumbrances?: string;          // mortgages, usufructs, leases
    notes?: string;
  }[];

  corporate_interests: {
    company: string;
    registration_number?: string;
    shareholding_pct?: number;
    role?: string;                  // director, shareholder, beneficial owner
  }[];

  // Cross-border structures — common in both corporate and family matters
  // Foreigners cannot own land in Thailand directly. Common workarounds:
  cross_border_structures: {
    type: 'usufruct' | 'long_lease' | 'superficies' | 'nominee_structure' | 'thai_company' | 'condo_freehold';
    property_ref?: string;          // chanote number or address
    counterparty?: string;          // Thai landowner, company, etc.
    expiry?: string;                // lease/usufruct end date — critical for family disputes
    notes?: string;
  }[];

  foreign_assets?: string;          // narrative — Thai clients with overseas assets
  known_liabilities?: string;       // debts, guarantees, judgments against
  asset_notes?: string;             // freeform — attorney observations
}
```

---

### Layer 3 — Behavioural Profile
This is the layer that exists only in the attorney's head today. It builds over time through direct experience. It is the most valuable part of the KB for a returning client.

```typescript
interface BehaviouralProfile {
  // Communication style
  communication_under_stress: string;
    // e.g. "Goes quiet for days then sends 10 messages at once"
    // e.g. "Calls repeatedly when anxious — needs proactive updates to prevent this"
    // e.g. "Stays calm, businesslike, always responds within an hour"

  decision_speed: 'fast' | 'considered' | 'slow' | 'defers_to_others';
  decision_notes?: string;
    // e.g. "Always consults husband before agreeing to anything"
    // e.g. "Signs off quickly but changes mind later — get written confirmation"

  // Receptiveness to advice
  follows_legal_advice: 'always' | 'usually' | 'sometimes' | 'rarely';
  advice_notes?: string;
    // e.g. "Pushes back on cost estimates but ultimately follows recommendation"
    // e.g. "Tends to want to fight everything — requires realistic outcome framing early"

  // Outcome expectations
  expectation_management: 'realistic' | 'optimistic' | 'needs_careful_management';
  expectation_notes?: string;

  // Reliability
  document_responsiveness: 'prompt' | 'average' | 'slow' | 'unreliable';
  payment_reliability: 'prompt' | 'average' | 'slow' | 'chases_required';
  reliability_notes?: string;

  // History of difficulty
  past_difficulty?: string;
    // e.g. "Disputed invoice in 2024 — resolved but keep billing summaries detailed"
    // e.g. "Previously unhappy with response times — always acknowledge within 2 hours"

  // Emotional context (particularly relevant for family matters)
  emotional_context?: string;
    // e.g. "Divorce is contentious — avoid any communication that could be used against her"
    // e.g. "Grieving — family estate matter, handle with patience"
}
```

---

### Layer 4 — Relationship Profile
How the client fits into the firm's network and any standing instructions.

```typescript
interface RelationshipProfile {
  sensitivity: 'standard' | 'high' | 'vip';
  referral_source?: string;         // who introduced them — matters if it's a key referrer
  referral_source_contact?: string;

  // Standing instructions — things always true regardless of matter
  standing_instructions: string[];
    // e.g. "Always copy CFO on all substantive correspondence"
    // e.g. "All documents must be in English regardless of Thai originals"
    // e.g. "Do not call — LINE only"
    // e.g. "Wife must not be informed of this matter"

  // Confidentiality within the firm
  restricted_access?: string[];     // staff who should not see this client's files

  relationship_notes?: string;      // anything else that shapes how the firm works with them
}
```

---

### Layer 5 — Matter History
Accumulates automatically as matters close. Powers the case strategy agent over time.

```typescript
interface MatterHistorySummary {
  matter_id: string;
  matter_number: string;
  type: string;
  opened: string;
  closed?: string;
  status: string;

  // Outcome
  outcome: 'won' | 'settled' | 'lost' | 'withdrawn' | 'ongoing';
  outcome_notes: string;

  // Strategic notes (attorney-authored at close)
  what_worked: string;
  what_didnt: string;
  opposing_counsel?: string;
  opposing_counsel_notes?: string;    // how they behaved, their tendencies
  judge_notes?: string;               // if relevant for future matters in same court

  // Financial
  total_billed: number;
  total_collected: number;
  retainer_returned?: number;
}
```

---

### Layer 6 — Auto-Brief Template
Generated when a new matter opens for an existing client. Pulls from all layers.

```
CLIENT BRIEF — [Matter Number] — Generated [timestamp]

[CLIENT NAME] · [Individual/Corporate] · [Sensitivity level]

CONTACT PREFERENCE
  Channel: [preferred_channel]  Language: [preferred_language]
  Key decision makers: [decision_influencers]
  Standing instructions: [standing_instructions]

BEHAVIOURAL PROFILE
  Under stress: [communication_under_stress]
  Decision making: [decision_speed] — [decision_notes]
  Follows advice: [follows_legal_advice] — [advice_notes]
  Payment: [payment_reliability]  Documents: [document_responsiveness]
  [past_difficulty if any]

ASSET SNAPSHOT
  [real_property list]
  [corporate_interests list]
  [foreign_assets if any]

MATTER HISTORY ([count] prior matters)
  [Most recent 3 matter summaries — type, outcome, what worked, opposing counsel]

RELEVANT PRIOR EXPERIENCE
  [AI-retrieved: prior matters most similar to this one by type and asset profile]

CONFLICT CHECK
  Status: CLEAR / FLAGGED
  Run: [timestamp]

RELATIONSHIP NOTES
  Referral: [referral_source]
  [relationship_notes]
```

---

## Questions to Resolve with Attorney

- [ ] Which behavioural fields matter most for family vs. corporate clients — are they the same?
- [ ] How should restricted_access work — by name, by role, or both?
- [ ] What does "VIP" mean operationally — different response SLA, attorney-only contact, or something else?
- [ ] Should opposing counsel notes be per-matter or shared across all matters (some opposing counsel repeat)?
- [ ] Are there client types that need additional profile fields not covered here?
- [ ] How detailed should judge/court notes be — is there value in tracking outcomes per judge?
- [ ] Standing instructions — should these trigger alerts when violated, or just display as reminders?
