Release Candidate: Production Release with Multi-Tenant & Onboarding Enhancements

2026-02-28 20:06:26 +05:30
parent 08a1f4a1d8
commit 4828274cbf
162 changed files with 19489 additions and 4300 deletions
--- a/writer/ANIME_STORY_BIBLE_IMPLEMENTATION.md
+++ b/writer/ANIME_STORY_BIBLE_IMPLEMENTATION.md
@@ -0,0 +1,431 @@
+# Anime Story Bible – Design & Implementation (Story Writer SSOT)
+
+This document is the single source of truth for the **Anime Story Bible** in Story Writer: what it is, where it lives in the codebase, how it is generated, and how it is used across outline, story text, images, and motion/animation.
+
+---
+
+## 1. Core Concepts
+
+- **Anime Story Bible**: Structured description of characters, world, and visual style for anime-style stories. It is designed to be:
+  - Stable across the whole story (single bible per story)
+  - Machine-readable (Pydantic/TypeScript models)
+  - Reusable for text, image, and video prompts
+
+- **Design Goals**
+  - Maintain **character consistency** across scenes and media
+  - Maintain **world rules** (tech/magic, constraints) throughout the narrative
+  - Maintain a **coherent anime visual style** across images and motion clips
+  - Allow future reuse for other story templates and media pipelines
+
+---
+
+## 2. Data Model (Backend & Frontend)
+
+### 2.1 Backend Models
+
+File: [story_models.py](file:///c:/Users/diksha%20rawat/Desktop/ALwrity/backend/models/story_models.py)
+
+Key classes:
+
+- `AnimeCharacter`
+- `AnimeWorld`
+- `AnimeVisualStyle`
+- `AnimeStoryBible`
+
+They are defined as:
+
+- `AnimeCharacter`
+  - `id`: stable snake_case identifier
+  - `name`
+  - `age_range`
+  - `role` (protagonist, antagonist, mentor, etc.)
+  - `look` (key visual details)
+  - `outfit_palette`
+  - `personality_tags: List[str]`
+
+- `AnimeWorld`
+  - `setting` (locations and general world description)
+  - `era` (near-future, alt 1990s, etc.)
+  - `tech_or_magic_level`
+  - `core_rules: List[str]` (constraints and consistent rules)
+
+- `AnimeVisualStyle`
+  - `style_preset` (anime_manga, cinematic_anime, cozy_slice_of_life, etc.)
+  - `camera_style`
+  - `color_mood`
+  - `lighting`
+  - `line_style`
+  - `extra_tags: List[str]`
+
+- `AnimeStoryBible`
+  - `story_id?: str`
+  - `main_cast: List[AnimeCharacter]`
+  - `world: AnimeWorld`
+  - `visual_style: AnimeVisualStyle`
+
+The bible is attached to:
+
+- `StorySetupOption.anime_bible: Optional[AnimeStoryBible]`
+- `StoryOutlineResponse.anime_bible: Optional[AnimeStoryBible]`
+
+Additionally, for downstream usage:
+
+- `StoryGenerationRequest.anime_bible: Optional[Dict[str, Any]]`
+- `StoryContinueRequest.anime_bible: Optional[Dict[str, Any]]`
+
+This allows story-start and continuation to receive a JSON-serializable bible blob without strict coupling to the `AnimeStoryBible` class.
+
+### 2.2 Frontend Models
+
+File: [storyWriterApi.ts](file:///c:/Users/diksha%20rawat/Desktop/ALwrity/frontend/src/services/storyWriterApi.ts)
+
+Types mirror the backend:
+
+- `AnimeCharacter`
+- `AnimeWorld`
+- `AnimeVisualStyle`
+- `AnimeStoryBible`
+
+The bible flows through:
+
+- `StoryOutlineResponse.anime_bible?: AnimeStoryBible`
+- `StoryGenerationRequest.anime_bible?: AnimeStoryBible | null`
+- `StoryStartRequest` and `StoryContinueRequest` (via `StoryGenerationRequest`)
+
+State layer:
+
+File: [useStoryWriterState.ts](file:///c:/Users/diksha%20rawat/Desktop/ALwrity/frontend/src/hooks/useStoryWriterState.ts)
+
+- `StoryWriterState.animeBible: any | null`
+- `setAnimeBible` setter
+- Persisted and restored via `localStorage`:
+  - Saved under `animeBible` key in the serialized state
+  - Ensures the bible survives refreshes
+
+---
+
+## 3. Bible Lifecycle & Generation
+
+### 3.1 Generation Source
+
+The Anime Story Bible is generated in the **story setup / outline** pipeline on the backend:
+
+- The story setup step produces a single `StorySetupOption` enriched with `anime_bible` when the selected template is anime-focused.
+- The outline generation step (`StoryOutlineResponse`) carries `anime_bible` so the UI can display it and store it in Story Writer state.
+
+SSOT:
+
+- Models: [story_models.py](file:///c:/Users/diksha%20rawat/Desktop/ALwrity/backend/models/story_models.py)
+- Outline response: `StoryOutlineResponse.anime_bible`
+
+### 3.2 Frontend Storage and Access
+
+The frontend receives `anime_bible` from `StoryOutlineResponse` and:
+
+- Stores it in `StoryWriterState.animeBible`
+- Persists it in `localStorage` with the rest of the story writer state
+- Exposes it to:
+  - Director chip / bible viewer UI
+  - Story generation (start/continue)
+  - Scene animation (via `story_context`)
+
+Key locations:
+
+- State hook: [useStoryWriterState.ts](file:///c:/Users/diksha%20rawat/Desktop/ALwrity/frontend/src/hooks/useStoryWriterState.ts)
+- Outline phase UI: [StoryOutline.tsx](file:///c:/Users/diksha%20rawat/Desktop/ALwrity/frontend/src/components/StoryWriter/Phases/StoryOutline.tsx)
+
+---
+
+## 4. Integration Points (Current Implementation)
+
+This section documents how the Anime Story Bible is currently used across the Story Writer pipelines.
+
+### 4.1 Story Text Generation (Start & Continue)
+
+#### 4.1.1 Requests
+
+Frontend:
+
+- `StoryGenerationRequest` (base)
+  - Now includes `anime_bible?: AnimeStoryBible | null`
+- `getRequest()` in `useStoryWriterState` adds `anime_bible` automatically:
+
+  - [useStoryWriterState.ts:getRequest](file:///c:/Users/diksha%20rawat/Desktop/ALwrity/frontend/src/hooks/useStoryWriterState.ts#L420-L461)
+
+Story start:
+
+- `StoryWriting.handleGenerateStart`:
+  - Builds `request = state.getRequest()`
+  - Calls `storyWriterApi.generateStoryStart(premise, outline, request)`
+  - [StoryWriting.tsx](file:///c:/Users/diksha%20rawat/Desktop/ALwrity/frontend/src/components/StoryWriter/Phases/StoryWriting.tsx#L308-L328)
+
+Story continue:
+
+- `StoryWriting.handleContinue`:
+  - `request = state.getRequest()`
+  - Builds `continueRequest = { ...request, premise, outline, story_text }`
+  - Calls `storyWriterApi.continueStory(continueRequest)`
+  - [StoryWriting.tsx](file:///c:/Users/diksha%20rawat/Desktop/ALwrity/frontend/src/components/StoryWriter/Phases/StoryWriting.tsx#L377-L388)
+
+Backend:
+
+- `StoryGenerationRequest` / `StoryContinueRequest` include `anime_bible: Optional[Dict[str, Any]]`
+  - [story_models.py](file:///c:/Users/diksha%20rawat/Desktop/ALwrity/backend/models/story_models.py#L11-L43)
+  - [story_models.py](file:///c:/Users/diksha%20rawat/Desktop/ALwrity/backend/models/story_models.py#L243-L259)
+
+#### 4.1.2 Routing Layer
+
+File: [api/story_writer/routes/story_content.py](file:///c:/Users/diksha%20rawat/Desktop/ALwrity/backend/api/story_writer/routes/story_content.py)
+
+- `generate_story_start`:
+
+  ```python
+  story_start = story_service.generate_story_start(
+      premise=request.premise,
+      outline=outline_data,
+      persona=request.persona,
+      story_setting=request.story_setting,
+      character_input=request.character_input,
+      plot_elements=request.plot_elements,
+      writing_style=request.writing_style,
+      story_tone=request.story_tone,
+      narrative_pov=request.narrative_pov,
+      audience_age_group=request.audience_age_group,
+      content_rating=request.content_rating,
+      ending_preference=request.ending_preference,
+      story_length=story_length,
+      anime_bible=getattr(request, "anime_bible", None),
+      user_id=user_id,
+  )
+  ```
+
+- `continue_story`:
+
+  ```python
+  continuation = story_service.continue_story(
+      premise=request.premise,
+      outline=outline_data,
+      story_text=request.story_text,
+      persona=request.persona,
+      story_setting=request.story_setting,
+      character_input=request.character_input,
+      plot_elements=request.plot_elements,
+      writing_style=request.writing_style,
+      story_tone=request.story_tone,
+      narrative_pov=request.narrative_pov,
+      audience_age_group=request.audience_age_group,
+      content_rating=request.content_rating,
+      ending_preference=request.ending_preference,
+      anime_bible=getattr(request, "anime_bible", None),
+      story_length=story_length,
+      user_id=user_id,
+  )
+  ```
+
+#### 4.1.3 Service Layer Prompts
+
+File: [story_content.py](file:///c:/Users/diksha%20rawat/Desktop/ALwrity/backend/services/story_writer/service_components/story_content.py)
+
+- `StoryContentMixin.generate_story_start(...)` now accepts `anime_bible: Optional[Dict[str, Any]]` and injects a serialized bible block right after the persona prompt:
+
+  ```python
+  anime_bible_context = ""
+  if anime_bible:
+      try:
+          serialized_bible = json.dumps(anime_bible, ensure_ascii=False, indent=2)
+      except Exception:
+          serialized_bible = str(anime_bible)
+      anime_bible_context = f"""
+
+  You also have a structured ANIME STORY BIBLE that defines the main cast, world rules, and visual style. Use it as a hard constraint for character consistency, worldbuilding, and visual storytelling:
+
+  {serialized_bible}
+  """
+  ```
+
+  The context is included for both short-story and longer-story prompts. This ensures:
+
+  - Character, world, and style constraints are explicitly visible to the LLM
+  - The same bible is applied consistently for start and continuation
+
+- `StoryContentMixin.continue_story(...)` similarly accepts `anime_bible` and injects the same `anime_bible_context` into the continuation prompt, directly after `persona_prompt`.
+
+This means every text generation step (start and continue) is conditioned on the bible when present.
+
+### 4.2 Scene Animation (Image-to-Video)
+
+The current bible-aware integration is focused on **motion prompts** for Kling image-to-video.
+
+#### 4.2.1 Frontend: story_context payload
+
+File: [StoryOutline.tsx](file:///c:/Users/diksha%20rawat/Desktop/ALwrity/frontend/src/components/StoryWriter/Phases/StoryOutline.tsx)
+
+`createStoryContextPayload` includes `anime_bible`:
+
+```ts
+const createStoryContextPayload = () => ({
+  persona: state.persona,
+  story_setting: state.storySetting,
+  characters: state.characters,
+  plot_elements: state.plotElements,
+  writing_style: state.writingStyle,
+  story_tone: state.storyTone,
+  narrative_pov: state.narrativePOV,
+  audience_age_group: state.audienceAgeGroup,
+  content_rating: state.contentRating,
+  story_length: state.storyLength,
+  premise: state.premise,
+  outline: state.outline,
+  story_content: state.storyContent,
+  anime_bible: state.animeBible,
+});
+```
+
+This payload is passed to:
+
+- `storyWriterApi.animateScene(...)`
+- `storyWriterApi.animateSceneVoiceover(...)`
+
+#### 4.2.2 Backend: Kling animation service
+
+File: [kling_animation.py](file:///c:/Users/diksha%20rawat/Desktop/ALwrity/backend/services/wavespeed/kling_animation.py)
+
+- `animate_scene_image(...)` is unchanged in signature but passes `story_context` to `generate_animation_prompt(...)`.
+
+- `_build_fallback_prompt(scene_data, story_context)`:
+  - Reads `anime_bible = story_context.get("anime_bible")`
+  - Extracts:
+    - Visual style details (`style_preset`, `camera_style`, `color_mood`, `lighting`, `line_style`, `extra_tags`)
+    - World `setting`
+    - `main_cast` names
+  - Appends a concise style text to the deterministic fallback prompt to preserve:
+    - Visual style
+    - World flavor
+    - Character design consistency (names only)
+
+- `generate_animation_prompt(scene_data, story_context, user_id)`:
+  - Builds an `ANIME STORY BIBLE VISUAL GUIDANCE` block when `anime_bible` is present, e.g.:
+    - Visual style preset and camera style
+    - Color mood, lighting, line style
+    - Extra style tags
+    - Main cast names to keep visually consistent
+    - World/setting context
+  - Inserts this block between `Setting` and the “Focus on” bullet list in the LLM prompt.
+  - Both structured JSON responses and fallback text generation flows see this block.
+
+Result:
+
+- Motion prompts for Kling image-to-video are constrained by the bible, making animations conform to:
+  - The same anime visual style
+  - The same character set
+  - The same world tone
+
+### 4.3 Images (Current State)
+
+Image generation currently uses:
+
+- `StoryScene.image_prompt` generated during outline generation
+- Image provider settings (width, height, model)
+
+The anime bible is not yet used in a **second-pass image prompt rewriter**. However:
+
+- The bible is already aligned with the same outline and template that produced `image_prompt`.
+- The bible is threaded into Story Writer’s state and can be used later to refine image prompts or add style constraints.
+
+Planned enhancement (not yet implemented):
+
+- Add a lightweight prompt refinement step that:
+  - Takes `scene.image_prompt` + `AnimeStoryBible.visual_style`
+  - Emits a style-constrained `final_image_prompt`
+  - Passes that to the image generation service
+
+This document should be updated when that enhancement is implemented.
+
+---
+
+## 5. Adapting the Bible to Other Story Types
+
+Although the Anime Story Bible is currently wired for anime-focused stories, the architecture is intentionally reusable.
+
+### 5.1 Reuse Strategy
+
+- **Data model**:
+  - `AnimeStoryBible` is anime-specific, but the concept of a structured “story bible” (cast + world + style) is general.
+  - Future story types can introduce sibling models (e.g., `NovelStoryBible`, `ComicStoryBible`) reusing similar patterns.
+
+- **Transport layer**:
+  - Requests use a flexible `anime_bible: Optional[Dict[str, Any]]` at the story-generation level.
+  - This can be generalized to a `story_bible` field if we want cross-template reuse.
+
+- **Prompt patterns**:
+  - Both text and motion pipelines use the same pattern:
+    - Serialize the bible
+    - Inject a dedicated paragraph or bullet block
+    - Explicitly instruct the model to treat it as a hard constraint
+  - This pattern is template-agnostic and can be reused for other story modes.
+
+### 5.2 Extension Guidelines
+
+When adapting the bible pattern to other story types:
+
+1. **Define the bible model**
+   - Add a dedicated Pydantic model under `story_models.py`.
+   - Mirror it with a TypeScript interface in `storyWriterApi.ts`.
+
+2. **Attach it to responses**
+   - Extend the relevant response models (setup, outline, etc.) with an optional bible field.
+   - Ensure the generating service populates it when the template supports it.
+
+3. **Thread through state**
+   - Add a field to `StoryWriterState`.
+   - Persist it in `localStorage`.
+   - Provide setter(s) and ensure it is included in `getRequest()` when relevant.
+
+4. **Inject into prompts**
+   - Text: add a serialized bible context block after the persona prompt for:
+     - Story start
+     - Story continuation
+   - Media: add a structured guidance block to:
+     - Image prompt generation (if using AI to build prompts)
+     - Motion/animation prompts
+
+5. **Document the flow**
+   - Update this document (or a sibling doc) with:
+     - Model definitions
+     - Where the bible is generated
+     - Where and how it is injected into prompts
+
+---
+
+## 6. Summary of Recent Changes (Bible Wiring)
+
+This section summarizes the concrete changes made for the initial Anime Story Bible integration:
+
+- **Backend models**
+  - Added `anime_bible` to `StoryGenerationRequest` and `StoryContinueRequest` as `Optional[Dict[str, Any]]`.
+  - Confirmed `AnimeStoryBible` and related classes in [story_models.py](file:///c:/Users/diksha%20rawat/Desktop/ALwrity/backend/models/story_models.py).
+
+- **Frontend models & state**
+  - Added `anime_bible?: AnimeStoryBible | null` to `StoryGenerationRequest`.
+  - `useStoryWriterState.getRequest()` now includes `anime_bible: state.animeBible || null`.
+  - `createStoryContextPayload` for outline/animation includes `anime_bible: state.animeBible`.
+
+- **Story text prompts**
+  - `generate_story_start` and `continue_story` accept `anime_bible` and inject a serialized “ANIME STORY BIBLE” context block directly after `persona_prompt`.
+  - Routing layer passes `request.anime_bible` through from API to service.
+
+- **Motion prompts (Kling image-to-video)**
+  - `story_context.anime_bible` is used in:
+    - `_build_fallback_prompt` to append style/world/cast hints to deterministic prompts.
+    - `generate_animation_prompt` to add an explicit `ANIME STORY BIBLE VISUAL GUIDANCE` block for the LLM.
+
+- **Not yet implemented**
+  - Second-pass enrichment of per-scene `image_prompt` using the bible.
+  - Generalization beyond anime templates (would require broader “story bible” abstraction).
+
+This document should be kept up to date whenever the Anime Story Bible is:
+
+- Extended to new story templates
+- Used for additional media types (e.g., storyboard export, trailers)
+- Modified in structure or prompt integration
+
--- a/writer/STORY_STUDIO_SSOT.md
+++ b/writer/STORY_STUDIO_SSOT.md
@@ -0,0 +1,337 @@
+# Story Studio – Single Source of Truth (SSOT)
+
+## 1. Vision and Positioning
+
+- **Product name**: Story Studio (evolution of Story Writer).
+- **What it is**: A narrative engine plus lightweight movie studio that turns brand and product context into structured stories, scenes, and multimedia assets.
+- **Role in ALwrity**: One of several “surfaces” driven by the same contextual brain (onboarding data, personas, SEO, competitive analysis), alongside Blog Writer, YouTube Creator, Podcast Maker, and Video Studio.
+
+### Core positioning
+
+- **Campaign Story Engine** (primary):
+  - Generates product stories, brand manifestos, founder narratives, and customer journey stories.
+  - Uses onboarding + persona + SEO context so stories are on-brand and strategically aligned.
+- **Story Studio / Fiction mode** (secondary):
+  - High-quality freeform stories (including anime / fantasy), primarily for GSC traffic and creative users.
+  - Lives “one click deeper” in the UI so marketing-first use cases stay front and center.
+
+Story Studio is not just “a novelist playground”; it is the narrative layer that can feed:
+- YouTube Creator (scripts and scenes),
+- Podcast Maker (episodic story arcs),
+- Video Studio (scene-wise video generation),
+- Blog and social content (campaign narratives).
+
+---
+
+## 2. Modes and Templates
+
+### 2.1 Modes
+
+- **Marketing Narratives (default)**:
+  - Entry path for ALwrity users arriving from the main app.
+  - Story types:
+    - Product Story (feature-driven but narrative-first).
+    - Brand Manifesto / “Why we exist”.
+    - Founder Story / Mission Arc.
+    - Customer Case Story (problem → journey → outcome).
+  - All marketing modes must:
+    - Pull from onboarding canonical_profile (brand, product, audience, pain points).
+    - Respect persona tone and style.
+    - Optionally weave in SEO pillars and competitor differentiation language.
+
+- **Pure Story Mode (creative)**:
+  - Entry path for GSC traffic and direct Story Studio users.
+  - Story types:
+    - Freeform fiction.
+    - Anime / manga stories.
+    - Experimental narrative formats.
+  - Marketing alignment:
+    - Gently surfaces the idea: “Turn this into a video / campaign” via export options.
+
+### 2.2 Template system
+
+For each template, define:
+- Required fields: goal, target audience, setting, length, POV, style, tone.
+- Optional fields: persona to anchor voice, product/context attachments.
+- Output shape:
+  - Premise (1–2 sentences).
+  - Outline (scenes with structured metadata).
+  - Story text (segments).
+  - Multimedia plan (per scene: image prompt, audio cue, video emphasis).
+
+Initial templates:
+- **Product Story**:
+  - Uses onboarding product data (features, benefits, differentiators).
+  - Structure: origin → tension → solution → proof → future.
+- **Brand Manifesto**:
+  - Uses canonical_profile (mission, values, audience).
+  - Structure: problem with status quo → belief → promise → invitation.
+- **Founder Story**:
+  - Uses founder/persona context if available, otherwise guided questionnaire.
+  - Structure: “before” life → trigger moment → struggle → insight → creation of the product.
+- **Customer Case Story**:
+  - Uses ICP + persona + pain-point data.
+  - Structure: “Customer X had problem Y” → discovery of solution → implementation → quantified outcome.
+- **Anime / Storyverse**:
+  - Style, visuals, and multimedia prompts oriented toward anime / stylized output.
+
+---
+
+## 3. Context Inputs (Data and Signals)
+
+Story Studio should treat ALwrity’s context as first-class inputs:
+
+- **Onboarding / canonical_profile**:
+  - brand_pitch, positioning, audience, products/services, content pillars.
+- **Personas**:
+  - core persona plus platform adaptations (tone, structure, constraints).
+- **SEO and competitors**:
+  - core keywords, sitemap analysis, competitive positioning and gaps.
+- **User preferences**:
+  - story length, style, tone, POV, “safe vs experimental”, multimedia intensity.
+
+Implementation:
+- Extend Story Setup to optionally show:
+  - “Use my brand & product data” toggle.
+  - Dropdown/select for which persona to write from.
+  - Pre-filled prompts using SEO pillars and competitor gaps.
+- State builder (`getRequest()` in useStoryWriterState) should:
+  - Attach canonical_profile / persona IDs or snapshots when marketing templates are used.
+
+---
+
+## 4. Text Model Strategy
+
+### 4.1 Roles
+
+- **Structured outline + scenes**:
+  - Use `llm_text_gen` with `json_struct` for:
+    - Scene lists (scene_number, title, description).
+    - Per-scene image_prompt, audio_narration, character_descriptions, key_events.
+  - Requirements:
+    - High reliability on JSON output.
+    - Good adherence to scene progression instructions.
+
+- **Narrative generation (story text)**:
+  - Use `llm_text_gen` in text mode for:
+    - Premise, story start, continuation until word-count targets.
+  - Requirements:
+    - Style controllability (tone, genre, age group).
+    - Long-context coherence for medium/long stories.
+
+### 4.2 Providers and models
+
+Use the existing provider abstraction:
+
+- **OSS/primary**: HF-backed models (Llama 3.1 8B, Mistral 7B, Qwen2.5) for cost-effective long-form and experimental modes.
+
+Decisions:
+- Keep model selection internal for now (no UI dropdown).
+- Introduce a simple “Quality vs Speed vs Cost” preset internally mapped to:
+  - High quality: Gemini or best OSS model.
+  - Balanced: OSS instruct model (e.g., Llama 3.1 8B, Mistral 7B).
+  - Experimental: more creative / higher-temperature models.
+
+Story length control remains as defined in story-writer-architecture.mdc:
+- Short (~1k words): one-shot.
+- Medium (<5k): multi-step.
+- Long (~10k): multi-step with IAMDONE marker.
+
+---
+
+## 5. Multimedia Model Strategy
+
+Multimedia generation must reuse existing studio infrastructure rather than invent new stacks.
+
+### 5.1 Images
+
+- Use StoryImageGenerationService as primary:
+  - Provider: stability / other configured HF/Gemini image models.
+  - Inputs: per-scene `image_prompt` derived from outline and template.
+  - Templates:
+    - Realistic marketing visuals (product-focused).
+    - Anime / stylized visuals (for anime mode).
+
+### 5.2 Audio
+
+- Use StoryAudioGenerationService:
+  - Providers: gTTS, pyttsx3, or any configured TTS provider.
+  - Inputs: `audio_narration` per scene (or compressed scene text).
+  - For campaign stories:
+    - Voice selection aligned with brand persona (calm, energetic, authoritative).
+
+### 5.3 Video
+
+- Use StoryVideoGenerationService for stitching scenes:
+  - Inputs:
+    - `image_urls` or `video_urls` per scene.
+    - `audio_urls` per scene.
+    - `fps`, `transition_duration`.
+  - For advanced/hero scenes, optionally integrate Video Studio models:
+    - text-to-video models (Hunyuan, LTX-2) for key moments.
+    - image-to-video (WAN 2.5, Kandinsky 5 Pro) for stylized sequences.
+
+### 5.4 Modes
+
+- **Standard story video**:
+  - Use existing story video pipeline.
+  - Emphasis on timeline, readability, and voiceover.
+- **Anime / stylized video**:
+  - Switch scene prompts + model selection to anime-friendly setups.
+  - Use more dynamic transitions for “story trailer” feel.
+
+---
+
+## 6. Phase Flow (Reframed for Story Studio)
+
+Core phases remain as in story-writer-architecture.mdc but with clarified responsibilities:
+
+1. **Setup**:
+   - Choose mode: Marketing Narrative vs Pure Story.
+   - Select template (Product Story, Brand Manifesto, etc.).
+   - Toggle/use brand context (onboarding, personas, SEO).
+   - Configure image/audio/video settings.
+
+2. **Outline**:
+   - Generate structured outline with scenes via `json_struct`.
+   - For marketing templates:
+     - Ensure each scene maps to a stage in the campaign story arc.
+   - For anime/fiction:
+     - Emphasize “world, characters, conflicts” and visual richness.
+
+3. **Writing**:
+   - Generate story text based on length settings.
+   - Enforce length controls and completion detection.
+   - Show word count and target in UI.
+
+4. **Multimedia / Export**:
+   - Generate scene images, audio, and video using configured settings.
+   - Allow:
+     - Export as story video (using StoryVideoGenerationService).
+     - Export scenes and script to:
+       - YouTube Creator (for adaptation to YouTube-specific script + scenes).
+       - Video Studio (for advanced editing or alternative visual styles).
+
+5. **Reset**:
+   - Keep existing reset semantics (clears state, localStorage, phases).
+
+---
+
+## 7. Implementation Plan
+
+### Phase 1 – Positioning and UX tweaks
+
+- Rename surface in UI copy to “Story Studio” where appropriate (keep routes/IDs stable to preserve GSC).
+- Add mode selector in Setup:
+  - Marketing Narratives (default).
+  - Pure Story.
+- Add template selector for marketing mode:
+  - Product Story, Brand Manifesto, Founder Story, Customer Story.
+- Adjust landing screen messaging to emphasize:
+  - “Turn your brand and product into narrative campaigns.”
+
+### Phase 2 – Context integration
+
+- Extend Story Setup state to store:
+  - `useBrandContext` flag.
+  - `selectedPersonaId` (optional).
+  - `selectedProductId` or product context stub.
+- Update `getRequest()` to include:
+  - References or snapshots from canonical_profile (where available).
+- Update backend story_service to:
+  - Accept and pass context into prompts (premise, outline, story start, continuation).
+
+### Phase 3 – Template-specific prompts
+
+- Design prompt templates per marketing template:
+  - Product Story, Brand Manifesto, Founder Story, Customer Story.
+- Encode:
+  - Clear arcs (setup → conflict → resolution).
+  - Use of brand and persona parameters.
+  - Explicit constraints on tone, length, POV.
+- For pure story mode:
+  - Provide genre/style toggles, including anime.
+
+### Phase 4 – Multimedia presets
+
+- Define multimedia presets for:
+  - Marketing Story (clean product visuals, muted transitions).
+  - Anime Story (bold colors, stylized prompts, dynamic transitions).
+  - Trailer Mode (shorter, punchier video composition).
+- Map presets to:
+  - Image generation prompt scaffolds.
+  - Video settings (fps, transition_duration).
+  - Potential future mapping into Video Studio model choices.
+
+### Phase 5 – Cross-surface exports
+
+- Implement export from Story Studio to:
+  - YouTube Creator:
+    - Export scenes as a JSON payload that can seed plan/scenes.
+  - Video Studio:
+    - Export scenes with associated image/audio references to pre-populate a project.
+- Add UI affordances:
+  - “Send to YouTube Creator”.
+  - “Open in Video Studio”.
+
+### Phase 6 – Hardening and metrics
+
+- Ensure:
+  - Subscription / usage checks per story generation and multimedia call.
+  - Caching behavior for repeated outline/story generations when context unchanged.
+  - Task management and polling remain consistent with existing story_writer architecture.
+- Add metrics:
+  - How many Story Studio sessions start in marketing vs pure modes.
+  - How many flows export to YouTube/Video Studio.
+
+---
+
+## 9. Current Implementation Status (Feb 2026)
+
+- Modes and templates:
+  - Marketing vs Pure Story modes are wired through Story Setup state and backend prompts.
+  - Template identifiers (e.g. `product_story`, `brand_manifesto`, `founder_story`, `customer_story`, `short_fiction`, `long_fiction`, `anime_fiction`, `experimental_fiction`) are resolved in service components for label-aware prompts.
+- Context integration:
+  - Story context endpoint exposes `canonical_profile`-derived `brand_context` and `brand_assets` for Story Studio.
+  - Story Setup modal can toggle use of onboarding brand persona when in marketing mode, and surfaces avatar and voice preview where available.
+- AI Setup modal:
+  - Dedicated AI Setup modal drives an idea → setup flow.
+  - “Enhance Story Idea” uses a dedicated backend endpoint to enhance only the freeform idea text, preserving intent and avoiding premature setup field generation.
+  - “Continue to Story Setup” generates exactly three structured setup options and, on selection, pre-fills Story Setup fields (persona, setting, characters, plot, style, tone, POV, audience, rating, ending, length, premise) plus image/video/audio defaults.
+  - UI includes rotating, mode-aware idea placeholders and an AI-style, animated glow frame around the story idea textarea to emphasize the primary input surface while keeping the overall theme light and readable.
+- Multimedia defaults:
+  - Story Setup state carries image/video/audio settings and can accept per-option overrides from generated setups.
+  - Story Outline and StoryImageGenerationModal integrate with the shared image generation stack, including provider/model selection and cost-awareness.
+- Video integrations:
+  - HD video configuration section exposes provider/model dropdowns with story-based defaults, aligned with the broader Video Studio architecture.
+
+---
+
+## 10. Next Steps for Story Studio
+
+- Deepen template-specific prompts:
+  - Tighten prompt templates per marketing template so setup options encode clearer arcs and brand positioning, especially for product_story and customer_story.
+  - Expand fiction/anime prompt variants to better control pacing and recurring characters across scenes.
+- Refine idea-to-setup bridge:
+  - Add light-touch guidance in the AI Setup modal to help users iterate between idea enhancement and setup generation (e.g. suggested follow-up edits based on the last enhancement).
+  - Capture telemetry on how often users enhance the idea before generating setups to tune prompts and thresholds.
+- Multimedia and cross-surface flows:
+  - Wire Story Studio’s outline and scene structures into “Send to YouTube Creator” and “Open in Video Studio” actions, including carrying over multimedia presets.
+  - Introduce preset bundles for “Standard Story”, “Anime Story”, and “Trailer Mode” that automatically adjust image/video defaults and, where available, Video Studio model choices.
+- Reliability and guardrails:
+  - Add targeted monitoring around the AI Setup endpoints (idea enhancement and setup generation) for latency, error rates, and JSON validity.
+  - Continue to enforce subscription and usage checks consistently across Story Studio, Blog Writer, and Video Studio so billing and limits remain unified.
+
+---
+
+## 8. Guardrails and Non-Goals
+
+- Do not:
+  - Turn Story Studio into a separate codebase; keep it within the existing Story Writer architecture and services.
+  - Fragment context handling; continue to use canonical_profile and existing persona services as SSOTs.
+- Guardrails:
+  - Maintain strict story length controls.
+  - Keep subscription handling centralized via `triggerSubscriptionError`.
+  - Continue to use structured JSON for outlines and scene metadata wherever possible.
+
+This document, together with `story-writer-architecture.mdc` and the existing Story Writer implementation docs in `docs/story writer/`, serves as the SSOT for evolving Story Writer into Story Studio.