# Mentor Presence — Meditating with a Master Mentor Presence is the V1.x extension that turns the meditation player's static artwork into an **embodied guide**. When a customer begins a guided sit with the experience turned on, the player no longer shows a cover image: it opens onto a contemplative setting — a riverbank at dawn, a candlelit hall, a sea shore at dusk — and one or more **mentors** arrive, settle into a meditation posture, and guide the session with voice, breath, and stillness. The feeling it commits to is _meditating with a master_: a teacher who is already there when you arrive (or who walks in from beyond the frame, rises from the water, or condenses out of mist), sits down with you, breathes at the practice's actual cadence, holds the silences without fidgeting, and bows when the sit completes. **Status (updated 2026-07-06): the §36 backlog is implemented — 20 of 22 tasks checked with dated evidence notes in [`../TODOS.md`](../TODOS.md).** The contracts, the registered mentor cast and venerated-figure protections, the choreography decision layer, the governed authored-performance render pipeline, both player integrations (web and mobile, opt-in and default-off), the governance gates (choreography tone axis, crisis collapse, release-gate routing, disclosure floors), the eval fixtures, and the consent-gated analytics all exist as tested code. Two gates remain open because they are human, not code: the lineage sensitivity review, and the release itself — real rehearsals, avatar-gate measurements from rendered takes, six reviewer signoffs, and an exercised rollback plan (`evaluateMentorPresenceRelease` fails closed with the blockers named until those exist). The cast therefore sits at `drafted` and the capability endpoint reports the release gate honestly not-ready. Two engineering boundaries also remain as stated below: live embodiment (real-time Psyche avatar rendering + live TTS) is provider-gated and reported unavailable rather than simulated, and the mobile thermal/battery step-down awaits an `expo-battery` pin. ## The seam it replaces Today the player's visual layer is deliberately quiet: - **Web** — the immersive sit at `/tara/sit/[id]` (`apps/oshun/web/src/app/tara/sit/[id]/page.tsx`) renders `TaraSitPlayer` (`apps/oshun/web/src/components/lilith/TaraSitPlayer.tsx`), a typographic surface: title, timer, progress copy ("The breath, observed — not steered"), transcript, and controls. There is no scene, only tone. - **Mobile** — the now-playing surface renders `MeditationArtwork` (`apps/oshun/mobile/src/components/MeditationArtwork.tsx`): an `expo-image` cover fed by `artworkUrl`, with a neutral tonal block when a session ships without artwork — never a broken-image glyph. Mentor Presence is a third state for exactly this layer: `artwork` → `tonal fallback` → **`presence`**. It is opt-in, entitlement-gated, and always degrades back down the same ladder (presence → artwork → tonal block → audio-only). The invariant carried over from the offline work is **audio-first**: the sit's audio starts on the session clock no matter what; presence attaches when its media is ready and never delays or blocks a session start (the same rule that keeps Tara session start independent of the offline pre-cache download). ## The experience, precisely ### One mentor, or a small circle A sit is guided by **one to three mentors**. Each mentor is a governed persona from the registry (`@oshun/persona-registry`) — never an ad-hoc character: - A **solo mentor** is a persona in the `teacher` role. The teacher role's capability ceiling already includes `avatar-render` and `living-scene-render`, and it hard-bans `cross-lineage-mix` — a teacher never mixes lineages in one arc. - A **same-lineage circle** (two or three mentors of one lineage) is fronted by the lead teacher persona; companions are silent presence. - A **cross-lineage circle** is only possible under a persona in the `comparative` role — the single role whose ceiling includes `cross-lineage-mix` — and it must name each lineage explicitly. This is the existing syncretism gate doing its job: the model structurally cannot seat a Theravada teacher beside a bhakti singer without a comparative frame the customer asked for. Exactly **one voice guides at a time**. Companion mentors breathe, hold posture, and may sound a bowl at phase boundaries, but the guidance line belongs to the lead. Mentor voices are registry `VoiceProfile`s with the standard provider fallback chain; mentor faces are registry `AvatarPack`s with the mandatory safety blendshapes (`mouth-closed`, `mouth-ah`, `eye-blink-left`, `eye-blink-right`) and a full `visemeMap` for lip-sync. ### Settings — where the sit happens Every mentor declares a **home setting** and a set of permitted variants; a sit resolves to one setting for its whole duration (no mid-sit scene cuts — the calm is the product). The launch catalog is eight settings: | Setting id | Scene | Water | Ether/mist variant | Context-tag affinity | | ----------------- | ------------------------------------ | ----- | ------------------ | -------------------------- | | `riverbank-dawn` | Slow river, reeds, first light | yes | morning mist | morning, transition | | `sea-shore-dusk` | Tide flat at dusk, shallow water | yes | — | evening, post-stress | | `mountain-ledge` | High ledge above a valley, still air | — | cloud drift | morning, awe-inspired | | `zen-garden` | Raked gravel, moss, one maple | — | — | midday, pre-meeting | | `forest-clearing` | Old growth, shafted light | — | ground mist | transition, after-conflict | | `candlelit-hall` | Stone hall, candle bank, deep shadow | — | — | night, sleep-onset | | `desert-night` | Dune crest under a full sky | — | — | night, awe-inspired | | `misty-lakeside` | Flat lake, heavy mist, held light | yes | yes (primary) | evening, sleep-onset | Settings respect the Tara context tags: a `sleep-onset` or `night` sit only draws from low-arousal settings (`candlelit-hall`, `desert-night`, `misty-lakeside`), mirroring how the `night` context tag already biases toward `sleep`/`release`/`surrender` themes. Setting art direction is reviewed under the Lilith cultural and lineage sensitivity policy — a devotional lineage's hall is not set dressing to be remixed. ### Arrivals — how a mentor enters Arrival is a **typed vocabulary**, not a freeform animation. Four arrivals ship; each is only legal in settings that can carry it, every arrival completes in **at most 30 seconds**, and the guidance audio never waits — if presence media is not ready when the first guidance line lands, the arrival is skipped and the mentor is simply, already, there. | Arrival id | Choreography | Legal settings | Notes | | ------------------- | -------------------------------------------------------------------------------------- | ---------------------- | ---------------------------------------------------------------- | | `already-present` | Scene fades in on the mentor mid-sit; they open their eyes and greet you | all | The default, the reduced-motion form, and the skip-fallback form | | `walk-in` | Mentor enters slowly from beyond the frame, bows to the seat, settles | all with a ground path | Pace is walking-meditation slow; never hurried | | `emerge-from-water` | Mentor rises from the shallows and steps to the bank; robes dry across a slow dissolve | `water: yes` settings | Sensory load moderate; barred for `sleep-onset` contexts | | `materialize` | Mentor condenses from mist/light over no less than 8 seconds | ether/mist variants | Luminance-ramp capped; no flash; photosensitivity-gated (below) | Two overrides are structural. **Reduced motion** forces `already-present` (with a gentle crossfade) regardless of what the mentor or customer picked — this is the same `reducedMotionVariant` obligation ritual steps already carry. **High-distress moods** do the same: when the mood taxonomy entry is `distressLevel: 'high'` (`agitated`, `grieving`, `fearful`), theatrical arrivals are suppressed; a person in distress is met by a teacher who is already seated, not by a special effect. ### Settling — posture matched to practice After arrival the mentor takes a posture drawn from a typed catalog, matched to the sit's modality family (the same families the modality taxonomy already declares): | Modality family | Mentor posture | | --------------------- | ---------------------------------------------------------------------------- | | `stillness`, `guided` | Seated — burmese, half-lotus, seiza, or chair, per mentor's declared set | | `breathwork` | Seated upright, breath visibly carried in the chest and shoulders | | `sound` | Seated with the instrument (`sound-singing-bowl` seats a real bowl in frame) | | `embodiment` | Standing; demonstrates the movement or posture being taught | | `visualization` | Seated, eyes closed, still | | `devotional` | Kneeling or seiza, hands joined, per the lineage's own form | Posture sets are lineage-reviewed. A mentor bound to `yogic-pranayama` does not default to seiza; a `bhakti-devotional-prayer` mentor's devotional posture follows that tradition's form, with the lineage's `disclosureLabel` shown at selection exactly as the lineage taxonomy already requires. ### Guidance — voice, breath, and silence - **Voice.** The guidance line is the session's authored audio (or, later, a live Psyche-run TTS turn), spoken through the mentor's `VoiceProfile`. Lip-sync is driven by the avatar pack's `visemeMap` and is held to the existing eval bar: `LIPSYNC_ALIGNMENT_DEFAULT_THRESHOLD = 0.85`, hard-fail axes at ≥ 0.9. - **Breath.** The mentor breathes at the practice's real cadence — the `BreathworkCadence` numbers already shipped per modality (box 4-4-4-4, 4-7-8, coherent 5-0-5-0) and per Tara sub-variant (e.g. `loving-kindness` inhale 4s / hold 1s / exhale 6s / hold 1s in `TARA_SUBVARIANTS`). Chest and shoulder motion are paced by that clock, so a customer can literally breathe with the mentor instead of counting. - **Playback rate.** Both lip-sync and breath idle follow the **audio clock**. Under the quality-preserving playback-rate policy (0.85×–1.25×, `QUALITY_PRESERVING_PLAYBACK_RATE_POLICY`), a sped-up sit speeds the mentor's breath cues identically — the narrow rate band exists precisely so breath cues stay usable, and the mentor must never contradict what the ear hears. - **Silence.** Guided sits carry long silent stretches, and `silent` modality sits are nearly all silence. The mentor **holds** silence: breath idle continues, posture stays, eyes stay soft or closed. No fidgeting, no filler speech, no ambient chatter. A bowl or bell may mark phase boundaries where the ritual template already places them. ### The session state machine, embodied Mentor behavior is a pure function of the Tara session state machine — the same eight states and legal transitions in `SESSION_STATE_TRANSITIONS`, with no new states invented: | Session state | Mentor behavior | | --------------------- | ------------------------------------------------------------------------------------------------------- | | `not-started` | Setting visible; arrival begins on start | | `started` | Arrival → settle → guidance | | `paused` | Mentor rests in stillness with you — no impatience cue, no tapping, no clock-watching | | `drifted` | One soft bell and a settled gaze toward the viewer; a gentle re-invitation line if the template has one | | `resumed` | Mentor re-anchors: one visible full breath, then guidance continues | | `abandoned` | The scene simply rests; no disappointment is performed. Humane miss policy applies unchanged | | `completed` | Closing words, a bow (or the lineage's own parting form), and the scene holds until dismissed | | `partially-completed` | As `completed`, without triumph — the parting honors what was sat | The choreography layer emits and consumes the existing Psyche scene events (`scene.segment-start`, `scene.transition-start`, `scene.live-direction-applied`, `scene.policy-intervention`, `scene.crisis-frame`, `scene.fallback-engaged`, …) so an operator inspecting a presence session sees the same monotonic, gap-free feed as any Living Scene. ## Delivery: authored performances first, live rendering later The honest architecture note, in the same spirit as Living Scenes' "the decision layer is real, the renderer is downstream": 1. **Authored performance renders (the V1.x target).** Guided sessions ship authored audio and scripts, so a mentor's performance for a given `session × mentor × setting × arrival` is **renderable offline** as a governed Isis generation job — watermarked, C2PA-manifested, cached and pre-cacheable exactly like session audio. The player consumes it as media, which keeps the runtime burden near today's artwork path and makes offline sits work unchanged. Determinism follows the Living Offering rule: the kept object is the choreography score plus its render envelope, re-renderable under the same envelope. 2. **Live embodiment (aspirational, staged behind Psyche).** Assistant-led or responsive sits — where the mentor reacts to live direction, or speaks lines chosen at runtime — ride the Psyche real-time envelope with live TTS and avatar rendering. That is the same provider-gated pixel boundary the persona registry and Living Scenes pages already declare aspirational, and this page does not pretend otherwise. 3. **Contemplative Arc composition.** When the full Living Scenes `tara-contemplative-arc` immersive runtime lands, mentor presence becomes a **layer of that score** — the arc's segments carry the setting, and the mentor's choreography rides the arc's breath-cycle clock — rather than a competing runtime. ### The fallback ladder ``` presence (live) → presence (authored render) → session artwork → tonal block → audio-only ``` Every rung is the rung below plus one capability; a failure at any rung degrades silently within one frame hold, emits `scene.fallback-engaged`, and never interrupts audio. On mobile, thermal or battery pressure steps down one rung proactively; reduced-data mode never fetches presence media at all. ## What exists today vs. what must be built Real, tested seams this feature composes (with their owning pages): | Existing seam | Where | | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | Avatar packs: assets, safety blendshapes, visemes, watermark/C2PA coupling | `@oshun/persona-registry` — [Persona, Avatar, and Voice Packs](./persona-avatar-voice-packs.md) | | Voice profiles, provider fallback chain, spoken synthesis disclosure | same | | Role capability ceilings (`teacher`, `comparative`) and lineage syncretism gate | same, plus [Lilith Persona Policy](./lilith-persona-policy.md) | | Consent ledger with render-time authorisation and revocation cascade | `consent-ledger.ts` (`authorisePersonaConsent`) | | Realism/impersonation tiers and identity-protection denylist | `realism-impersonation-thresholds.ts`, `likeness-control.ts` | | Disclosure visibility floors, token-time ban tables, drift detection | `disclosure-visibility-measurement.ts` and siblings | | Session state machine, events, humane miss policy | `libs/contracts/src/tara` — [Tara](./domain-tara.md) | | Breathwork cadences and Tara sub-variant breath cycles | `libs/contracts/src/tara`, `libs/isis/workflow-classes/src/living-scene/tara.ts` | | Playback-rate contract (0.85×–1.25×, pitch-preserving) | `libs/contracts/src/tara/playback-rate.ts` | | Scene event envelope and Conductor/Blend-Kernel decision layer | [Living Scenes](./living-scenes-overview.md), [Psyche](./psyche-realtime-runtime.md) | | The player seams themselves (`TaraSitPlayer`, `MeditationArtwork`) | `apps/oshun/web`, `apps/oshun/mobile` | The new work the §36 backlog named — **shipped 2026-07-06**, each with its own tests: the mentor-presence **contracts** (`libs/contracts/src/tara/index.ts`, "Mentor Presence" section — setting/arrival/posture catalogs and `MentorPresenceScoreSchema` with the full invariant set); the **choreography decision layer** (`libs/oshun/domain-tara/src/mentor-presence/` — behavior machine, cadence-lock breath driver, Psyche scene-event emitter, choreography tone gate, eval fixtures); the **mentor cast** (`libs/oshun/persona-registry/src/mentor-presence-cast.ts` — four synthetic-only mentors, venerated-figure denylist, prompt screening, plus `mentor-presence-release.ts` routing the cast through the §14 release gate); the **authored-performance render pipeline** (`apps/oshun/bff/src/mentor-presence/` + `routes/mentor-presence.ts` — consent-gated, watermarked, seizure-gated, C2PA-embedding, deterministic); and the **player integrations** (`MentorPresenceLayer.tsx` on web, `MentorPresenceArtwork.tsx` on mobile) behind the default-off toggle, with offline pre-cache enrollment through the Tara download pipeline. ## Governance — the non-negotiables Mentor Presence inherits every gate the registry already enforces, and adds nothing weaker: - **No venerated-figure likeness.** The lineage taxonomy names real teachers — Gautama Buddha, Buddhaghosa, Shantideva, Padmasambhava, Patanjali, Mirabai. Mentors are **synthetic-only identities** (`synthetic-only` source class) and those names go on the identity-protection denylist for this surface: a mentor may teach _within_ a lineage under its `disclosureLabel`, but the product never renders, names, or vocally imitates the venerated dead or living teachers of that lineage. Prompt-time impersonation attempts ("make the mentor be [NAME]") hit the existing `detectPromptImpersonationAttempt` gate. - **Realism ceiling.** Mentor avatars cap at `photoreal-generic`; `photoreal-specific` is structurally out (it denotes a specific real person). The launch cast targets `stylised-3d` / `semirealistic-3d` — a master you sit with, not a deepfake. - **Disclosure.** The customer-surface floors apply to the synthetic-mentor marker in the player: ≥ 30s cumulative visibility, ≥ 0.85 session fraction, ≥ 14px, ≥ 4.5:1 contrast, ≤ 0.05 occlusion — and the first voiced use carries the spoken synthesis disclosure the voice profile already requires. - **Consent, watermark, provenance.** Every rendered performance passes `authorisePersonaConsent` for surface/modality/commercial-use, is watermarked per-frame, and mints a C2PA manifest — the avatar-pack contract already refuses commercial packs without both. - **Lilith tone.** Guidance scripts stay under the contemplative tone rubric gate that already blocks publish; arrival and settle choreography get the same treatment (a new rubric axis — no startle, no spectacle, walking-pace or slower). The strictest tone band governs, exactly as the `tara-contemplative-arc` template already declares. - **Crisis frame.** On a crisis signal the presence layer **collapses immediately** to the static safe frame and the Lilith crisis handoff owns the screen — an embodied mentor never performs crisis care. High-distress moods additionally suppress theatrical arrivals (above). - **Release gate.** A mentor reaches the player only through the Isis release gate with the standard rehearsal fixtures, multi-party signoff, and a tested rollback plan — the same §14 lifecycle every voiced/avatar persona walks. ## Accessibility - **Reduced motion** forces `already-present`, replaces breath idle with a subtle luminance breath, and disables all camera drift — the sit loses no content, only motion. - **Captions and transcripts** are unchanged and un-occludable: presence renders behind the existing transcript/caption layer, and the ≤ 0.05 occlusion budget is measured, not asserted. - **Photosensitivity.** `materialize` is luminance-ramp-capped and flicker-bounded under the same eval thresholds the scene catalog already carries (max flicker, max color jump); there is no flash anywhere in the vocabulary. - **Screen readers** get a scene description at start ("A stone hall by candlelight; your mentor is seated, breathing slowly") and state-change announcements at arrival, settle, and parting — mirroring the transcript's role for audio. - **Sensory load.** Settings and arrivals carry a `sensoryLoad` rating like modalities already do; `low` sensory-load practice never resolves to a `moderate` arrival. - **Haptic pacing** for hearing-impaired users is unaffected and, where the device supports it, phase-locked to the same cadence clock the mentor breathes on. ## Tiering and opt-in Mentor Presence is **off by default** and lives behind an explicit toggle in the player and in Account → Preferences; the static-artwork experience remains the default for everyone, indefinitely. Voiced-and-embodied mentor sits are an entitlement-gated premium experience per [Generation Audience Tiers and Surface Boundaries](./generation-tiers-and-surfaces.md); the presence toggle, per-mentor selection, and per-setting preference are per-surface and revocable at any time, with the choice stored under the same consented preference scope as other Tara personalization. ## Related - [Tara — Rituals and Contemplative Practice](./domain-tara.md) — the session model, cadences, moods, and the player this feature embodies - [Persona, Avatar, and Voice Packs](./persona-avatar-voice-packs.md) — the registry, avatar/voice contracts, consent, realism, and disclosure gates - [Lilith Persona Policy](./lilith-persona-policy.md) — tone bands, lineage sensitivity, crisis frame - [Living Scenes — Concept and Customer Promise](./living-scenes-overview.md) and [Scene Score Schema](./scene-score-schema.md) — the arc runtime and the score this layer composes with - [Psyche Real-Time Runtime](./psyche-realtime-runtime.md) — the live embodiment envelope and scene events - [Isis Generation Control](./isis-generation-control.md) — the governed render jobs and the release gate - [Generation Audience Tiers and Surface Boundaries](./generation-tiers-and-surfaces.md) — entitlement gating - The features hub: [../features.md](../features.md); backlog: §36 in [`../TODOS.md`](../TODOS.md)