Perpetual vs guest
Until 2026-05-16, every soul that appeared in a council was a *perpetual* soul: a fully-formed identity with its own standalone Obsidian vault under <obsidian-vault>/<soul>/. Pippa, Ttori, Buffett — each one needed full vault scaffolding before they could sit at the table.
That bar was too high for the case Dad kept hitting: he'd want to bring a *guest* into a council — a historical figure, a thought-experiment voice, a one-shot persona — without committing to building them a whole vault first. The old workaround ("roleplay persona") wasn't a soul at all; it was a temporary character sheet that didn't survive past the session.
Guest souls fix that. A guest soul is a real soul-like identity with:
- a scoped mini-vault under
~/Obsidian/guest-souls/<name>/instead of a full<obsidian-vault>/<soul>/tree; - real voice, avatar assets, selective memory, identity continuity;
- the ability to appear in multiple councils across sessions;
- a promotion path to perpetual status without losing identity continuity.
It's not a disposable persona. It's a soul that hasn't grown a full vault yet.
Three-layer identity
The 2026-05-16 v2 contract replaced "soul_id is just a string" with three layers:
- soul_pk — the immutable primary key, never reused, never changed.
- current_slug — the human-readable slug, can change (rename) without losing history.
- alias — display variants, locale-specific titles, casual references.
This matters because guest souls eventually promote into perpetual souls. The same identity needs to survive the slug change, the avatar refresh, the vault grow-out. soul_pk anchors continuity; everything else evolves around it.
Avatar fallback chain
Guest souls join councils as soon as Dad sketches them — sometimes before avatar assets exist. The avatar resolver falls back through: emotion-labeled portrait → soul-default portrait → soul initials chip. So a brand-new Zhuge Liang who has nothing but a name and an initials chip can still take a turn while his avatar set is being commissioned.
Promotion
When a guest soul has earned a full vault — enough memory, enough character depth, enough council appearances that Dad wants them at the table permanently — promotion is a flow, not a rename. The scoped mini-vault contents migrate into a full vault structure under <obsidian-vault>/<soul>/, the soul row flips a kind flag, and any past council turns keep referencing the same soul_pk. No history loss, no avatar churn, no "new soul" cold start.