From da2200ad2ab87f96362bc9254489cc6acc3dd1f7 Mon Sep 17 00:00:00 2001
From: Shinwoo PARK <shinwoo.park@psw.kr>
Date: Mon, 11 May 2026 17:47:23 +0900
Subject: [PATCH] docs: clarify freeform persona initialization

---
 API-Reference.md            |  7 +++++--
 Getting-Started.md          | 15 +++------------
 Home.md                     |  4 ++--
 Purpose-and-Architecture.md |  9 ++++++---
 4 files changed, 16 insertions(+), 19 deletions(-)

diff --git a/API-Reference.md b/API-Reference.md
index 8179a33..07273f7 100644
--- a/API-Reference.md
+++ b/API-Reference.md
@@ -29,7 +29,8 @@ initializePersona(db: IdentityDB, input: InitializePersonaInput): Promise<Initia
 **Important input fields**
 
 - `displayName: string`
-- `personality: string`
+- `seedText?: string`
+- `personality?: string`
 - `history?: string`
 - `values?: string[]`
 - `likes?: string[]`
@@ -41,9 +42,11 @@ initializePersona(db: IdentityDB, input: InitializePersonaInput): Promise<Initia
 - `generateProfileImage?: boolean`
 - `reuseExistingSpace?: boolean`
 
+`seedText` is the preferred initialize input shape: a single long freeform string that may already include personality, history, values, preferences, dislikes, and relationships. Structured fields remain available as optional supplemental hints and for backward compatibility.
+
 **Behavior**
 
-- generates a biography through `structuredModel`
+- generates a biography through `structuredModel`, using `seedText` as the primary source when provided
 - extracts fact drafts through `structuredModel`
 - writes biography facts into the persona space
 - optionally generates a profile image and writes a profile-image fact
diff --git a/Getting-Started.md b/Getting-Started.md
index b82d1c8..6266a60 100644
--- a/Getting-Started.md
+++ b/Getting-Started.md
@@ -102,18 +102,8 @@ const grok = createGrokAdapters({
 
 const persona = await initializePersona(db, {
   displayName: 'Mina',
-  personality: 'Thoughtful, witty, introverted, and emotionally observant.',
-  history: 'Raised in Busan, later moved to Seoul to work in product design.',
-  values: ['loyalty', 'self-respect', 'quiet consistency'],
-  likes: ['late-night walks', 'indie music', 'quiet cafés'],
-  dislikes: ['performative networking', 'loud restaurants'],
-  relationships: [
-    {
-      name: 'Jisoo',
-      relationship: 'older brother',
-      description: 'protective but teasing',
-    },
-  ],
+  seedText:
+    'Mina is a thoughtful, witty, introverted, and emotionally observant product designer. She was raised in Busan and later moved to Seoul for work. She values loyalty, self-respect, and quiet consistency, loves late-night walks, indie music, and quiet cafés, dislikes performative networking and loud restaurants, and stays especially close to her older brother Jisoo, who is protective but teasing.',
   currentDate: '2026-05-11',
   structuredModel: grok.structured,
   imageModel: grok.image,
@@ -126,6 +116,7 @@ console.log(persona);
 ### What initialization does
 
 - generates a detailed biography
+- can start from a single long freeform persona seed string
 - extracts IdentityDB-ready facts
 - creates or reuses an IdentityDB space (depending on options)
 - optionally generates a profile image
diff --git a/Home.md b/Home.md
index e38266d..8e7da76 100644
--- a/Home.md
+++ b/Home.md
@@ -21,7 +21,7 @@ In short: BoxBrain is a harness for building personas that have memory, history,
 - provider-agnostic adapter contracts for text, structured-output, image, and special-date retrieval
 - a ready-made xAI Grok adapter set for text, structured-output, and image generation
 - one IdentityDB **space** per persona as the primary isolation boundary
-- persona initialization from personality, history, values, likes, dislikes, and relationships
+- persona initialization from a long freeform seed string that the LLM breaks into biography-ready detail and IdentityDB facts
 - LLM-generated biography creation followed by fact extraction into IdentityDB
 - optional profile image generation during persona initialization
 - realistic schedule generation for day, week, and month scopes
@@ -52,7 +52,7 @@ These are **not** implemented as part of the core library yet:
 
 A BoxBrain persona works like this:
 
-1. **Initialize a persona** from structured traits and history.
+1. **Initialize a persona** from a long freeform seed string, optionally with extra structured hints.
 2. Generate a detailed biography.
 3. Extract biography facts and store them in the persona's IdentityDB space.
 4. Generate schedules anchored to time and external special dates.
diff --git a/Purpose-and-Architecture.md b/Purpose-and-Architecture.md
index 020948d..0c15c06 100644
--- a/Purpose-and-Architecture.md
+++ b/Purpose-and-Architecture.md
@@ -80,18 +80,21 @@ This is the mechanism that makes a persona feel like it has its own life rhythm.
 
 ## 1. Persona initialization
 
-Initialization takes explicit seed attributes such as:
+Initialization takes a long freeform seed string from the caller.
+
+That single string can contain things like:
 
-- display name
 - personality
 - history
 - values
 - likes / dislikes
 - relationships
 
+`displayName` still exists as a stable explicit field for runtime identity and space naming, and optional structured hints can still be provided as supplements when useful.
+
 Then BoxBrain:
 
-1. asks a structured model to generate a detailed biography
+1. asks a structured model to interpret the freeform seed and generate a detailed biography
 2. asks a structured model to split that biography into IdentityDB-ready facts
 3. persists those facts into the persona's IdentityDB space
 4. optionally generates a profile image through an image adapter