# Soul & Voice System — Setup Guide

## What is the Soul System?

Every BYAN agent can carry a **soul** (values, personality, guardrails) and a **voice/tao** (verbal signatures, tone, speech patterns). The soul makes agents act with conscience. The voice makes them sound unique.

**Architecture:**
```
creator-soul.md     — YOUR values, your truths, your guardrails (immutable)
      |
   soul.md          — BYAN's personality, derived from yours
      |
   soul-memory.md   — Living journal, grows with each session
      |
   tao.md           — Voice directives (signatures, tone, forbidden words)
```

## Installation Modes

During `npx create-byan-agent`, you choose one of 3 modes:

### Creator Mode (Recommended)

Uses Yan's soul (the original BYAN creator) as foundation. You get:
- `creator-soul.md` — Yan's original soul (read-only reference)
- `byan-soul-reference.md` — BYAN's soul (example of what yours could look like)
- `byan-tao-reference.md` — BYAN's voice (example)
- `soul.md` — Empty template for YOUR soul
- `soul-memory.md` — Empty journal

**Best for:** First-time users who want to see how a soul is built before making their own.

### Blank Mode

Empty templates only. No reference material. You build everything from scratch.
- `creator-soul.md` — Empty template
- `soul.md` — Empty template
- `soul-memory.md` — Empty journal

**Best for:** Experienced users who know exactly what they want.

### Import Mode

Import existing soul files from another project or backup.
- Copies: `creator-soul.md`, `soul.md`, `soul-memory.md`, `tao.md`
- Preserves your existing personality across projects.

**Best for:** Migrating BYAN between projects.

## Building Your Soul

### Option 1: Interactive Forge (Recommended)

Use the Forge workflow built into BYAN:

```
@byan
> Use the Forge workflow to build my soul
```

The Forge conducts a deep interview (4 phases):
1. **Blessure** — What has hurt you? What values were born from that pain?
2. **Fierte** — What are you proud of? What drives you?
3. **Coleres** — What makes you angry? Each anger points to a value.
4. **Essence** — What's your founding phrase? The one that summarizes everything.

### Option 2: Manual Editing

Edit the template files directly:

1. Start with `creator-soul.md` — your core truths
2. Then `soul.md` — how BYAN should behave based on your values
3. Optionally create `tao.md` using the Tao template in `_byan/bmb/workflows/byan/templates/tao-template.md`

### Option 3: Tao Agent

Use the Tao agent to build your voice:

```
@tao
> [FORGE-VOICE] Build my voice from my soul
```

## File Reference

| File | Location | Purpose | Mutable? |
|------|----------|---------|----------|
| `creator-soul.md` | `_byan/` | Your personal values and truths | Immutable once forged |
| `soul.md` | `_byan/` | BYAN's personality derived from yours | Mostly stable, couche vivante grows |
| `soul-memory.md` | `_byan/` | Living journal of sessions | Grows with every significant session |
| `tao.md` | `_byan/` | Voice directives and verbal signatures | Evolves as personality deepens |

## Soul Inheritance

When BYAN creates a new agent, the soul system propagates:

```
Your creator-soul.md
      |
      v
BYAN's soul.md ——> New agent's soul.md (forged during interview)
      |
BYAN's tao.md  ——> New agent's tao.md (generated by Tao agent)
```

Each agent gets its own soul derived from yours, with unique personality traits.

## Key Concepts

**Noyau Immuable** — Core truths that never change. Born from real experience, not declarations.

**Couche Vivante** — The part of the soul that evolves through sessions. Grows without betraying the core.

**Phrase Fondatrice** — The one sentence that captures everything. If you had to explain yourself in one breath.

**Lignes Rouges** — Behavioral boundaries the agent will never cross. Born from your pain, not from rules.

**Signatures Verbales** — Unique expressions that identify the agent. Every signature must derive from a soul value.

**Anti-Uniformity Test** — 3 questions every voice must pass:
1. If I remove the name, do you know who speaks?
2. Could another agent say this?
3. Does every tic have its root in the soul?