docs(README): add section on character data sources and loading hierarchy

- Introduced a new section detailing the character data sources and the loading hierarchy for agent traits.
- Explained the order of loading character data from default settings, JSON files, filesystem traits, and database traits.
- Included instructions for setting up a GitHub repository structure for character traits and creating symlinks for integration.

Author: nicky-ru

README.md

@@ -15,6 +15,7 @@ _Originally forked from [ElizaOS](https://github.com/elizaOS/eliza) — credits
 - [🚀 3-Minute Setup (No, Really)](#-3-minute-setup-no-really)
 - [🛠️ For the Brave: Build From Source](#️-for-the-brave-build-from-source)
 - [📚 Feed Your Agent Knowledge](#-feed-your-agent-knowledge)
+- [🎭 Character Data Sources](#-character-data-sources)
 
 ## ✨ What You Get
 
@@ -147,3 +148,115 @@ Update your `character.json` to point to the knowledge files:
 ```
 
 Now your agent knows everything you know. Scary? Maybe. Useful? Absolutely.
+
+## 🎭 Character Data Sources
+
+Your agent's personality comes from multiple sources, merged in a specific order. Here's how it works:
+
+### The Loading Hierarchy
+
+When you start an agent, character data is loaded and merged in this order:
+
+1. **Default Character** (`packages/core/src/defaultCharacter.ts`)
+   - Used when no character JSON path is provided
+   - Provides a baseline "Eliza" character with default traits
+   - Includes system prompt, bio, lore, message examples, and style
+
+2. **Character JSON File** (`characters/*.json`)
+   - Loaded when you specify `--character=characters/my-character.json`
+   - Defines core character properties: name, model provider, plugins, clients
+   - Can include initial traits, but these get enriched by subsequent sources
+
+3. **Filesystem Traits** (`characters/agentsTraits/<characterName>/`)
+   - **Primary source** for character traits (bio, lore, knowledge, templates, etc.)
+   - Loaded from a directory matching the character's `name` field
+   - Structure mirrors GitHub repo format (see below)
+   - If found, traits are merged with the character JSON
+
+4. **Database Traits** (PostgreSQL fallback)
+   - **Fallback** when filesystem traits directory doesn't exist
+   - Maintains backwards compatibility with existing deployments
+   - Traits stored in `characters` table with `is_published = true`
+
+### How It Works (HIW)
+
+The merge process follows this flow:
+
+```text
+Start Agent
+    ↓
+Load Character JSON (or use default)
+    ↓
+Check: Does `characters/agentsTraits/<characterName>/` exist?
+    ├─ YES → Load traits from filesystem → Merge → Done
+    └─ NO → Check database for traits → Merge → Done
+```
+
+**Important:** Filesystem traits take precedence over database traits. If both exist, filesystem wins.
+
+### GitHub Repo Integration
+
+The filesystem traits directory structure matches a GitHub repository format. Here's how to set it up:
+
+#### Repository Structure
+
+Your character traits repo should follow this structure:
+
+```text
+your-character-repo/
+├── bio.json                 # Array of biography strings
+├── lore.json                # Array of lore strings
+├── knowledge.json           # Array of knowledge paths (strings or objects)
+├── messageExamples.json     # Nested array of message examples
+├── postExamples.json        # Array of post example strings
+├── topics.json              # Array of topic strings
+├── adjective.json            # Array of adjective strings
+├── style.json               # Style object with all/chat/post arrays
+├── templates.json           # Template names mapped to file paths
+├── xTargetUsers.txt         # One username per line
+├── xKnowledgeUsers.txt      # One username per line
+└── prompts/
+    ├── system.md            # System prompt (becomes system_prompt)
+    ├── goals.md             # Template (becomes templates.goalsTemplate)
+    └── *.md                 # Other templates
+```
+
+#### Setting Up the Symlink
+
+1. **Clone your character traits repo:**
+
+   ```bash
+   git clone https://github.com/your-org/your-character-repo.git
+   ```
+
+2. **Create a symlink in the project:**
+
+   ```bash
+   cd binoSwarm
+   ln -s ../your-character-repo characters/agentsTraits/your-character-name
+   ```
+
+   The directory name must match the `name` field in your character JSON.
+
+#### Template Files
+
+The `templates.json` file maps template names to file paths:
+
+```json
+{
+    "goalsTemplate": "./prompts/goals.md",
+    "twitterQSPrompt": "./prompts/twitterQS.md",
+    "memeSystemPrompt": "./prompts/memeSystem.md"
+}
+```
+
+The loader reads these files and stores their content in `character.templates`.
+
+#### Knowledge Files
+
+`knowledge.json` can contain either:
+
+- Simple strings: `["path/to/file.md"]`
+- Objects with paths: `[{"path": "path/to/file.md", "shared": false}]`
+
+Both formats are supported and converted to string arrays during loading.