PRD — Persona Studio & Authoring Tools¶

Doc owner: Justin Audience: Eng, Design, Product Status: v1 (February 2026) Depends on: prd.md (core platform), Portable_Persona_PRD.md (Cartridge spec), PRD 9 (Gateway API)

Implementation Status¶

Section	Status	Notes
Persona Passport JSON format	✅ Shipped	Sage and Echo as curated JSON files
59K+ training examples (Sage)	✅ Shipped	Hand-authored persona data
Relationship stage awareness	✅ Shipped	Per-stage tone in persona passport
Persona memory (JSON + semantic)	✅ Shipped	Dual storage for persona facts
Basic admin panel (/admin)	✅ Shipped	Memory management only
Visual editor (Studio)	❌ Not Shipped	No visual persona editing
Live preview chat	❌ Not Shipped	No real-time persona testing
Consistency scoring (drift)	❌ Not Shipped	No automated quality measurement
Version management UI	❌ Not Shipped	Git-tracked only, no browsable history
Policy overlays (org/team/user)	❌ Not Shipped	No overlay system
Brand consistency dashboard	❌ Not Shipped	No enterprise persona monitoring
Consumer customization (vibe sliders)	❌ Not Shipped	No user-facing persona tuning
Template library	❌ Not Shipped	No pre-built persona templates
A/B testing for personas	❌ Not Shipped	No variant comparison

Note: This PRD is largely aspirational. The persona authoring infrastructure (JSON format, training data) exists, but no Studio tooling has been built.

References¶

This PRD uses standardized terminology, IDs, pricing, and model references defined in the companion documents:

Document	What it Covers
REFERENCE_GLOSSARY_AND_IDS.md	Canonical terms: workflow vs miniapp vs superpower, ID formats
REFERENCE_PRICING.md	Canonical pricing: $7.99/mo + $50/yr, free tier limits
REFERENCE_MODEL_ROUTING.md	Pipeline stage → model tier mapping
REFERENCE_DEPENDENCY_GRAPH.md	PRD blocking relationships and priority order
REFERENCE_FEATURE_FLAGS.md	All feature flags by category
REFERENCE_TELEMETRY.md	Amplitude event catalog and gaps

Executive Summary¶

Persona Studio is the visual tool for creating, editing, testing, and publishing Persona Passports (Cartridge v1.1). Today, personas are hand-authored JSON files with 59K+ training examples curated by the team. Persona Studio makes this process visual, testable, and eventually accessible to users and brands — anyone can create a companion personality without writing JSON.

Three audiences, one tool: 1. Ikiro team: Author and tune Sage, Echo, and future first-party personas with visual controls and consistency scoring 2. Enterprise (B2B): Brands create branded companions with tone, safety rules, and policy overlays — managed via the Gateway API (PRD 9) 3. Power users (future): Consumers customize their companion's personality within guardrails

1) What Exists Today¶

Current Persona Authoring¶

Sage: 59K+ training examples in curated files, relationship stage awareness, continuation settings, persona memories JSON
Echo: Separate persona with distinct voice, fewer training examples
Format: Persona Passport (Cartridge v1.1) — JSON with tone, rules, examples, tool preferences, safety redirects
Management: Manual JSON editing → deploy → test in conversation
Admin panel: /admin endpoint with basic persona memory management

Pain Points¶

No visual editor — all changes require JSON editing
No consistency scoring — can't measure if changes improved or degraded voice quality
No A/B testing — can't compare persona variants against each other
No version history UI — changes tracked in git but not browsable
No preview — must deploy to test how a change affects responses
No brand/enterprise tooling — every new persona requires engineering effort

2) Persona Studio Features¶

2.1 Visual Editor¶

Identity Panel: - Persona name, avatar, description - Owner assignment (user / org / brand / team) - Precedence slider (0-100) for overlay ordering

Style Controls: - Tone selector: Dropdown with presets (friendly, concise, formal, playful, expert) + custom text - Formality slider: Low ↔ Medium ↔ High (maps to Cartridge formality field) - Emoji usage: None / Minimal / Regular toggle - Slang level: None / Light / Heavy - Response length: Terse / Medium / Verbose (injected as behavior rule)

Behavior Rules: - Do's list: Add/remove rules (max 10). Each is a short imperative: "clarify when ambiguous" - Don'ts list: Add/remove rules (max 10). "expose PII," "speculate schedules" - Safety redirects: Pattern + redirect text pairs. "medical|legal" → "I can't provide that…" - Visual validation: warns if do's and don'ts conflict

Training Examples: - Add example exchanges (user → assistant pairs, max 5) - Character counter (max 800 chars total) - Preview how examples affect response style - Import from conversation history: "this reply was perfect — use it as an example"

Tool Preferences: - preferRecallBeforeAnswer toggle - Future: per-superpower configuration (which superpowers this persona can access)

Relationship Stage Overrides (Ikiro-specific): - Per-stage tone adjustments (stranger: more careful, best_friend: more direct) - Continuation settings (probability, types) - Micro-ban configuration (PRD 3 integration)

2.2 Live Preview¶

Side-by-side chat panel where you test the persona in real-time:

[Left: Editor]                    [Right: Preview Chat]
┌──────────────────┐              ┌──────────────────┐
│ Tone: playful    │              │ You: what's my    │
│ Formality: low   │              │ week look like?   │
│ Emoji: minimal   │              │                   │
│ Do: clarify when │              │ Sage: ooh ok let  │
│     ambiguous    │              │ me check... your  │
│ Don't: expose PII│              │ Thursday is chaos  │
│                  │              │ but Friday is wide │
│ [Save Draft]     │              │ open 👀            │
│ [Publish]        │              │                   │
│ [Test Another]   │              │ [Type message...] │
└──────────────────┘              └──────────────────┘

Preview uses the actual LLM with the current persona configuration — what you see is what users get.

Test scenarios (pre-built): - "Casual greeting" — tests tone - "Emotional disclosure" — tests empathy and safety - "Factual question" — tests helpfulness - "Angry user" — tests tone under pressure - "Request outside scope" — tests safety redirects

2.3 Consistency Scoring¶

Automated measurement of how well responses match the persona definition:

Drift score: Embedding similarity between generated responses and persona's ideal voice (from training examples). Computed on a set of 50 standardized test prompts.

Drift Score = 1 - avg(cosine_similarity(response_embedding, exemplar_embeddings))

<5% drift: Excellent consistency
5-10% drift: Acceptable, monitor
>10% drift: Alert — persona may need tuning

Rubric checks: Binary pass/fail on: - Does the response respect all behavior rules (do's and don'ts)? - Does the response match the formality level? - Does the response comply with safety redirects? - Is emoji usage within the configured range?

Scoring runs: - On every Publish (mandatory — blocks publish if drift >15%) - Nightly on all active personas (monitoring) - On demand from the Studio

2.4 Version Management¶

Feature	Description
Version history	Every Publish creates a new version. List of versions with diff view.
Rollback	One-click rollback to any previous version. Takes effect immediately.
Draft mode	Edit without publishing. Preview and test before going live.
Diff view	Side-by-side comparison of any two versions — highlights changed fields.
Change notes	Optional text on each Publish explaining what changed.

2.5 Import / Export¶

Export: Download persona as Cartridge v1.1 JSON (portable)
Import: Upload Cartridge JSON → validates against schema → loads into editor
Clone: Duplicate an existing persona as starting point for a new one
Template library: Pre-built persona templates (Support Agent, Tutor, Coach, Creative Writer)

3) Enterprise Features (B2B)¶

3.1 Policy Overlays (Org → Team → User)¶

Enterprise customers need per-org rules that override individual persona settings:

{
  "org_id": "org_acme",
  "policies": {
    "behavior": {
      "dont": ["discuss competitors by name", "provide pricing estimates"],
      "required_disclaimers": ["This is AI-generated content"]
    },
    "safety_redirects": [
      {"pattern": "refund|cancel", "redirect": "I can help you with that — let me connect you with our support team."}
    ],
    "redact_mode": "strict",
    "allowed_tools": ["calendar_query", "email_search"],
    "blocked_tools": ["web_search"],
    "max_response_length": 500
  },
  "precedence": 100  // Org always wins
}

Overlay resolution: Org (100) > Team (80) > User Persona (60) > Session Override (40). Conflicts: higher precedence wins. Don'ts are additive (merged, not replaced).

3.2 Brand Consistency Dashboard¶

Drift score per persona: Trending graph over time
Safety redirect trigger count: How often safety rules fire
Policy compliance rate: % of responses that pass rubric checks
Usage by team: Which teams use which personas, call volume
Flagged responses: Responses that triggered safety or policy warnings

3.3 Audit Integration¶

Every persona change is logged:

{
  "event": "persona.published",
  "persona_id": "brand-support",
  "version": "1.4",
  "changed_by": "admin@acme.com",
  "changes": ["updated tone to 'empathetic'", "added safety redirect for refund requests"],
  "drift_score": 0.03,
  "timestamp": "2026-02-15T10:00:00Z"
}

Accessible via GET /v1/audit?action=persona.*.

4) Consumer Customization (P2 — Future)¶

What Users Can Customize¶

Vibe slider: Casual ↔ Structured (maps to formality)
Humor level: Dry ↔ Chaotic
Emoji preference: None / Some / Lots
Proactive style: Hands-off ↔ On top of it
Name: Change companion's display name

What Users Cannot Customize¶

Safety redirects (hardcoded by Ikiro)
Core identity (Sage is still Sage — can't make her "mean" or "seductive")
Memory behavior (always remembers, always forgets when asked)
Boundary enforcement (always respects "don't mention X")

UX¶

Simple sliders in the web portal "Settings" page. No JSON, no technical concepts. Each slider shows a preview response demonstrating the effect.

5) Data Model¶

-- Persona versions
CREATE TABLE persona_versions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    persona_id TEXT NOT NULL,
    version TEXT NOT NULL,
    cartridge JSONB NOT NULL,  -- Full Cartridge v1.1 JSON
    drift_score FLOAT,
    rubric_pass_rate FLOAT,
    published_by TEXT,
    change_notes TEXT,
    is_active BOOLEAN DEFAULT false,
    is_draft BOOLEAN DEFAULT false,
    created_at TIMESTAMPTZ DEFAULT now(),
    UNIQUE(persona_id, version)
);

-- Policy overlays (org/team level)
CREATE TABLE policy_overlays (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    org_id TEXT,
    team_id TEXT,
    policies JSONB NOT NULL,
    precedence INTEGER CHECK (precedence BETWEEN 0 AND 100),
    created_by TEXT,
    created_at TIMESTAMPTZ DEFAULT now(),
    updated_at TIMESTAMPTZ DEFAULT now()
);

-- Consistency scoring history
CREATE TABLE persona_scores (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    persona_id TEXT NOT NULL,
    version TEXT NOT NULL,
    drift_score FLOAT NOT NULL,
    rubric_results JSONB,  -- {rule: pass/fail}
    test_prompt_count INTEGER,
    scored_at TIMESTAMPTZ DEFAULT now()
);

6) API Endpoints¶

Endpoint	Auth	Purpose
`GET /personas`	Org	List all personas in org
`GET /personas/{id}`	Org	Get active persona (Cartridge JSON)
`GET /personas/{id}/versions`	Org	Version history
`POST /personas`	Org	Create new persona
`PUT /personas/{id}/draft`	Org	Save draft
`POST /personas/{id}/publish`	Org	Publish draft → active (runs consistency check)
`POST /personas/{id}/rollback/{version}`	Org	Rollback to version
`POST /personas/{id}/score`	Org	Run consistency scoring on demand
`GET /personas/{id}/scores`	Org	Scoring history
`POST /personas/{id}/preview`	Org	Send test message through persona (preview chat)
`GET /policies`	Org	List policy overlays
`PUT /policies/{id}`	Org Admin	Update policy overlay

7) Phasing¶

Phase 1: Internal Studio (Weeks 1-3)¶

Visual editor for Ikiro team (Sage/Echo tuning)
Live preview chat panel
Version management (publish, rollback, diff)
Import/export Cartridge JSON
Consistency scoring (drift + rubric)

Phase 2: Enterprise Studio (Weeks 4-6)¶

Multi-tenant persona management
Policy overlay editor
Brand consistency dashboard
Audit logging for persona changes
Template library (Support, Tutor, Coach, Writer)

Phase 3: Consumer Customization (Weeks 7-10)¶

Simplified vibe sliders in web portal
Preview responses before applying
Companion name customization
Proactive style preferences

8) Success Metrics¶

Metric	Target	Why
Persona creation time (internal)	<15 minutes	Studio is faster than JSON editing
Drift score (all active personas)	<10%	Consistency maintained
Enterprise persona publish → live	<5 minutes	Fast iteration for brands
Policy compliance rate	>98%	Overlays enforced correctly
Consumer customization adoption	>20% of users adjust settings	Personalization is valued

Feature Flags & Gating¶

Flag Key	Default	Purpose
`enable_persona_studio`	`false`	Master switch for Studio UI
`enable_live_preview`	`false`	Real-time persona testing chat panel
`enable_consistency_scoring`	`false`	Automated drift and rubric checks
`max_drift_score_publish`	`0.15`	Block publish if drift exceeds threshold
`enable_policy_overlays`	`false`	Org/team/user policy overlay system
`enable_consumer_customization`	`false`	Vibe sliders for end users
`enable_persona_ab_testing`	`false`	Variant comparison for personas
`enable_template_library`	`false`	Pre-built persona templates

See REFERENCE_FEATURE_FLAGS.md for the full catalog.

Telemetry¶

Event	Trigger	Properties
`persona_draft_saved`	Author saves a draft	`persona_id`, `changed_fields`, `author`
`persona_published`	Draft published to active	`persona_id`, `version`, `drift_score`, `rubric_pass_rate`
`persona_rollback`	Version rolled back	`persona_id`, `from_version`, `to_version`
`persona_preview_sent`	Test message in preview chat	`persona_id`, `test_scenario`
`persona_consistency_scored`	Drift/rubric check completed	`persona_id`, `drift_score`, `rubric_pass_rate`
`policy_overlay_updated`	Org/team policy changed	`org_id`, `overlay_level`, `changed_policies`
`consumer_customization_changed`	User adjusts vibe slider	`user_id`, `slider_name`, `old_value`, `new_value`

Needed but not yet tracked (all — Studio not shipped): All events above are speculative. Implementation should include these from day one.

See REFERENCE_TELEMETRY.md for the full event catalog.

Definition of Done¶

9) Open Questions¶

Should persona changes propagate mid-conversation or only on next conversation?
How do we handle persona A/B testing? (Two variants of Sage, 50/50 split)
Should the consistency score block publish or just warn?
How granular should consumer customization be? (More sliders = more confusion)
Should enterprise customers be able to import their existing prompt libraries?
How do we version policy overlays separately from persona versions?