Personas

---
summary: "Personas: identities the user holds (freelancer, company director, private citizen) carrying tax data, signatures, and destination paths."
type: guide
last_updated: 2026-06-21
related:
  - docs/mandants.md
  - docs/structure.md
---

# Personas — Self-Identity Definitions

A persona represents an **identity the user holds**. It answers the
question *"which hat am I wearing right now?"* — freelancer, company
director, private citizen, client's project owner, etc.

Personas carry tax data, legal entity information, destination paths
for document filing, and signatures for outgoing correspondence. They
are read by skills and sub-agents (especially the `archivist`) to
route work to the correct legal context.

## Quick start

1. Check the examples: `docs/examples/personas/freelancer-example.yaml`
   and `docs/examples/personas/company-example.yaml`
2. Copy `identity/personas/_template.yaml` to `identity/personas/<your-id>.yaml` on
   your `user/*` branch (never commit personas to `main`)
3. Fill in your tax number, address, destinations, signature
4. Reference the persona from a routing context:
   ```yaml
   # workflow/contexts/<domain>.yaml — routing-rules SoT for a domain
   persona_ref: <your-id>
   # routing rules below reference destinations[<key>] from the persona
   ```

Your persona is now active whenever that context is loaded by a skill
(e.g. `doc-system` reading `workflow/contexts/doc-system.yaml`).

## Personas vs mandants — the core distinction

The Bridge has two similar-looking concepts. Keep them apart:

| | Persona | Mandant |
|---|---|---|
| **File location** | `identity/personas/<id>.yaml` | `identity/mandants/<id>.yaml` |
| **Represents** | An identity **the user holds** | A recipient **group the user addresses** |
| **`role:` field** | `self` (always) | not set / context-dependent |
| **Used by** | `document-intake`, invoice generation, signature blocks | `workflow/calendars/entries.yaml`, bridge-deck messaging tabs |
| **Answers** | "Under which legal entity do I file this?" | "To whom do I send this message?" |
| **Example** | "Me as freelancer" / "Me as UG CEO" | "My team at work" / "My family" |
| **bridge-deck** | Not rendered (role:self excluded) | Rendered as addressbook cards |
| **Tax data** | Yes (tax ID, VAT ID, advisor) | No |
| **Destinations** | Yes (filing paths) | No |

Short form: **personas are who I AM**, **mandants are who I SEND TO**.

A single real-world person can appear in both. For example, if you
have a company "Example UG" with you as CEO, you might have:

- `identity/personas/example-ug.yaml` → type:company, role:self, tax data
- `identity/mandants/<client>.yaml` → type:company, role:recipient, channels

The same physical email address can appear in both files — they
answer different questions.

## Types

| Type | Icon | Use case |
|------|------|----------|
| `individual` | 👤 | Natural person identity (freelancer, private citizen, sole proprietor) |
| `company` | 🏢 | Legal entity the user represents (Ltd., LLC, Inc., GmbH, UG, SA, …) |

## Schema

See `identity/personas/_template.yaml` for the full annotated schema. Key fields: