docs: clarify freeform persona initialization

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

Getting-Started.md

@@ -102,18 +102,8 @@ const grok = createGrokAdapters({
 
 const persona = await initializePersona(db, {
   displayName: 'Mina',
-  personality: 'Thoughtful, witty, introverted, and emotionally observant.',
+  seedText:
-  history: 'Raised in Busan, later moved to Seoul to work in product design.',
+    '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.',
-  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',
-    },
-  ],
   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

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.

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