Persona Manager (archived 2026-05-25 — pre-Tavus-rename snapshot)

🗄️ Archived 2026-05-25. These docs describe the persona-manager module as of 2026-05-25, mid-rename to Tavus Manager (tracked in #630 / #632). The content is frozen on this archive path; do not edit it in place. Live docs will be added under docs/tavus/ (or the equivalent post-rename location) when the rename completes.

If you're looking for the current state of the system, check /ops/personas/* in the app, the open issues #630 and #632, and the future docs/tavus/ directory.

Persona Manager

⚠️ Naming transition (2026-05-23): "Persona Manager" is being split into two named surfaces:

Specialist Meetings — the client-facing onboarding + reporting video flows (moved to /client/specialists/[id]/* in #632). Old /client/admin/specialists/[id]/* paths return 308 redirects.

Tavus Manager — the SuperAdmin-only catalog management at /ops/personas/* (rename to /ops/tavus/* tracked in #630).

This README still describes the system as one unit. The split is being driven through #630 + #632.

Two video-conversation workflows on top of h.work.

What it does

Workflow	Purpose	Who it's for	Output
Onboarding	Single ~60-min structured video intake with the AI Specialist when a client first deploys it.	Client manager	An Environment Profile (systems, processes, vocabulary, guardrails, stakeholders, priorities) that the Specialist uses as operating context day-to-day.
Reporting	Periodic or ad-hoc video check-in with the Specialist.	Client manager	Decisions, priority changes, escalations, environment-change flags, scheduled next check-in — all captured as durable, audited rows.

The video frontend is Tavus. The system prompts, brief assembly, function-call dispatch, audit, and the queue/escalation surface all live inside the existing h.work API.

Architecture in a paragraph

A meeting record is created in the new meetings table (onboarding | reporting). The API renders a per-meeting system prompt from agent/prompts/{onboarding,reporting}_meeting.txt, fetches the active function-call definitions for the meeting kind from tavus_function_definitions, then calls Tavus to create a persona and a conversation. The conversation URL goes back to the client manager. As the call progresses, Tavus posts function-call events to /tavus/webhooks/function-call (HMAC-SHA256 verified, Redis-deduped). Those events route to onboarding handlers (which mutate the environment_profiles row) or reporting handlers (which write meeting_decisions + the existing actions table, and route escalations through ExpertQueueService.createQueueItem). Socket.io events (meeting_started, meeting_function_call, meeting_completed) fan out on the existing /notifications namespace.

Integration philosophy

We added new modules to the existing monorepo without modifying production code. The full philosophy is in prompts/archive/persona-builder.md and ADR-0001 below. Three permitted touches to existing files:

frontend/src/lib/api.ts — additive functions only.
api/src/app.module.ts — single-line module imports + imports[] entries.
.github/workflows/nightly-isolation.yml — additive entity entries.

Every other existing file is read-only.

File map

api/src/
  tavus/                          Tavus client, webhook verifier, router,
                                  function-call CRUD + controller
  environment-profiles/           env profile entity + service + onboarding
                                  function-call handlers + SOUL.md generator
  meetings/                       meeting/decision/priority entities,
                                  service (onboarding + reporting start),
                                  brief assembler, persona generator,
                                  reporting handlers, BullMQ cleanup processor
agent/prompts/
  onboarding_meeting.txt          system prompt for the onboarding persona
  reporting_meeting.txt           system prompt for the reporting persona
                                  (with {{ BRIEF_JSON }} placeholder)
api/migrations/
  1746000000010-PersonaManagerInit.ts        five new tables + RLS
  1746000000011-SeedPersonaManagerFunctions.ts 12 v1 function definitions
frontend/src/app/
  client/specialists/[id]/onboarding/         client-side onboarding flow
  client/specialists/[id]/meetings/           list, detail (start + outputs)
  ops/personas/function-calls/                SuperAdmin function-call CRUD
  ops/personas/replicas/                      SuperAdmin replica catalogue
  ops/personas/templates/                     SuperAdmin template reference
frontend/e2e/persona-manager/
  01-onboarding.spec.ts            full onboarding E2E
  02-reporting.spec.ts             full reporting E2E
  03-replica-not-set.spec.ts       negative 409 path
docs/
  decisions/persona-manager/ADR-0001-integration-approach.md
  specs/persona-manager-integration.md
  persona-manager/README.md (this file), api.md, function-calls.md

Configuration

Env var	Purpose
`TAVUS_API_KEY`	Auth for Tavus REST calls.
`TAVUS_API_BASE_URL`	Defaults to `https://tavusapi.com`. Override for staging.
`TAVUS_WEBHOOK_SECRET`	HMAC-SHA256 secret for verifying inbound webhooks. Hard-fails at boot in deployed envs if unset.
`TAVUS_DEFAULT_REPLICA_ID`	The Tavus replica id used as the default for persona creation.
`TAVUS_WEBHOOK_BASE_URL`	The public URL Tavus posts back to. Defaults to `APP_BASE_URL`.
`PERSONA_CLEANUP_AFTER_DAYS`	How old `ended_at` must be before the cleanup sweep archives a persona. Default `14`.
`PERSONA_CLEANUP_CADENCE_MS`	How often the BullMQ cleanup job runs. Default `86_400_000` (24h). Requires `REDIS_URL`.
`HWORK_ORGS_DIR`	Where SOUL.proposed.md files are written. Default: repo `orgs/` directory.
`HWORK_AGENT_PROMPTS_DIR`	Where the prompt templates live. Default: repo `agent/prompts/`.

Status

Phase 0 — Foundation: schema, entities, isolation env var ✓
Phase 1 — Tavus integration layer: client, webhook verifier, router, controller ✓
Phase 2 — Function-call library: CRUD, seed migration, SuperAdmin UI ✓
Phase 3 — Environment Profile + onboarding: service, handlers, SOUL.md generator, start endpoint, prompt, frontend ✓
Phase 4 — Brief assembly + reporting: brief assembler, persona generator, reporting handlers, Socket.io events, frontend ✓
Phase 5 — SuperAdmin surfaces: replicas catalogue, templates reference, audit-via-existing-viewer ✓
Phase 6 — Hardening: Playwright E2Es (skip-by-default unless PERSONA_MANAGER_E2E=1), cross-tenant isolation spec, BullMQ cleanup job, rate-limit inheritance ✓
Docs: this README, api.md, function-calls.md.

See BUILD_LOG.jsonl for the per-task trail and TODO_PERSONA.md for the canonical task list.

Persona Manager

What it does​

Architecture in a paragraph​

Integration philosophy​

File map​

Configuration​

Status​