Agentic Bilingual Kids Video Pipeline

Introduction

30 Second Summary

Heritage families know the feeling. You want your child to grow up speaking your language, understanding your culture, but daily life in another country makes it nearly impossible to teach structure, context, and meaning alongside vocabulary.

In this project, you will build a self-improving agentic system where a mother says a theme like "numbers" and 26 AI agents produce a JLPT-aligned bilingual video that teaches Japanese inside authentic cultural moments.

What You'll Build

A theme-triggered pipeline that orchestrates 26 specialized AI agents to produce bilingual educational videos combining JLPT-standard Japanese with cultural heritage immersion, fact-checked by adversarial cross-model review.

By the end of this project, you'll have:

• A theme-triggered video pipeline where saying a word like "fruits" produces a 5-minute bilingual video with language taught inside authentic Japanese cultural moments like a seasonal market visit.
• A 26-agent council with cross-model adversarial validation (Codex fact-checks Claude) ensuring JLPT accuracy, cultural fidelity, child engagement science, and safety compliance.
• A self-improving system that adapts as the child grows from 14 months through adulthood, with spaced repetition across episodes, seasonal cultural awareness, and quarterly source updates via Firecrawl.
• Secret Mission: Produce EP001 across all three visual formats, teaching numbers 1-5 inside a Japanese morning routine where a family counts steps to the genkan and rice bowls at breakfast.

Are there any prerequisites?

This project requires active subscriptions to Claude Max 20x, ChatGPT Plus (with Codex), Google AI Pro (for Nano Banana Pro image generation), and InstaDoodle Pro.

You also need a Windows 10/11 machine with an NVIDIA GPU (RTX 2060 Super or equivalent with 8GB VRAM), 32GB RAM, and Node.js, Python, and Git already installed. Step 1 verifies all versions and configurations.

Verify Your Environment and Install Core Tools

Twenty-six AI agents are about to build your bilingual video pipeline in parallel. Before they start, every tool they depend on must be present and at the right version.

In this step you will confirm your runtime versions, validate your GPU, test Japanese text-to-speech voices, and install the neural voice engine that will power your videos.

In this step, get ready to:

• Verify Node.js, Python, Git, npm versions and GPU availability.
• Confirm Japanese SAPI5 voices and test speech synthesis.
• Install piper-plus neural TTS and select the primary Japanese voice.

Verify existing tools

Every service in this project pins a minimum runtime version. A mismatched version causes silent failures later.

• Press the Windows key to open your search bar.
• Type PowerShell and press Enter to open it.

You will use PowerShell for all commands in this step.

• Check your Node.js version by running this command:

node --version

✔️ I see version 18 or higher

Your Node.js is ready. Move on to the Python check below.

ⓧ I see a version lower than 18

You need Node.js 18 or higher for Remotion rendering.

• Download the LTS installer from https://nodejs.org.
• Run the installer and accept the defaults.
• Close and reopen PowerShell, then run node --version again.

ⓧ Command not found

Node.js is not installed on this machine.

• Download the LTS installer from https://nodejs.org.
• Run the installer and accept the defaults.
• Close and reopen PowerShell, then run node --version again to confirm.

• Check your Python version by running:

python --version

✔️ I see version 3.11 or higher

Your Python meets the minimum for piper-plus. Continue below.

ⓧ I see a version lower than 3.11

piper-plus requires Python 3.11 or higher.

• Download the latest Python 3.11+ installer from https://www.python.org/downloads/.
• During installation, check Add python.exe to PATH.
• Close and reopen PowerShell, then run python --version again.
• If it still shows the old version, run python3.11 --version or use py -3.11 --version to target the new install.

ⓧ Command not found

Python is not installed on this machine.

• Download Python 3.11+ from https://www.python.org/downloads/.
• During installation, check Add python.exe to PATH.
• Close and reopen PowerShell, then run python --version to confirm.

• Check Git and npm versions by running these commands:

git --version
npm --version

What do these check?

Git manages the project repository your agents will scaffold. npm installs JavaScript packages for Remotion video rendering.

Both commands should output a version number. If either says "not recognized," install Git from https://git-scm.com and npm will come bundled with Node.js.

• Verify your NVIDIA GPU driver and CUDA availability by running:

nvidia-smi

What should I see?

The output table shows your GPU model (RTX 2060 Super), Driver Version, and CUDA Version in the header row. You need CUDA listed to confirm GPU-accelerated rendering will work.

nvidia-smi not recognized?

This means the NVIDIA driver path is not in your system PATH. The executable lives at C:\Program Files\NVIDIA Corporation\NVSMI\nvidia-smi.exe. Try running the full path directly. If the file does not exist, update your NVIDIA GPU drivers from https://www.nvidia.com/drivers.

Help me get nvidia-smi working on Windows

• Confirm Claude Desktop is installed with your Max 20x subscription active.
• Open Claude Desktop and verify you see Max in the plan indicator.
• Confirm ChatGPT Desktop is installed with Codex accessible.
• Open ChatGPT Desktop and verify the Codex feature is available in the sidebar.

Why two AI assistants?

Claude builds the pipeline. Codex independently fact-checks Claude's Japanese and cultural claims. Using two separate models prevents echo-chamber bias in educational content for children.

Verify SAPI5 Japanese voices

Windows ships with built-in Japanese speech synthesis voices. These serve as the fallback voice layer for your videos.

• Enumerate all available SAPI5 voices by running this command in PowerShell:

(New-Object -ComObject SAPI.SpVoice).GetVoices() | ForEach-Object { $_.GetDescription() }

What should I see?

The output lists every installed voice. Look for three Japanese entries: Microsoft Haruka Desktop (female), Microsoft Ichiro Desktop (male), and Microsoft Ayumi Desktop (female).

Missing Japanese voices?

If you do not see Haruka, Ichiro, or Ayumi, install the Japanese language pack. Open Settings then Time & Language then Language & Region. Add Japanese and ensure the Text-to-speech optional feature is checked.

Help me install Japanese SAPI5 voices on Windows

• Test Japanese speech synthesis with Haruka by running:

Add-Type -AssemblyName System.Speech; $s = New-Object System.Speech.Synthesis.SpeechSynthesizer; $s.SelectVoice("Microsoft Haruka Desktop"); $s.Speak("こんにちは")

You should hear a Japanese female voice say "konnichiwa" through your speakers.

No audio output?

Check that your default audio output device is set correctly. Right-click the speaker icon in the taskbar and select Sound settings to verify.

Install piper-plus and verify neural JP voice quality

SAPI5 voices work but sound robotic. piper-plus is a neural TTS engine that produces natural-sounding Japanese speech using the tsukuyomi-chan model. This will be your primary voice for video narration.

• Install piper-plus by running:

pip install piper-plus

What is piper-plus?

piper-plus (v1.12.0, MIT licensed) is the active fork of the archived rhasspy/piper project. It uses OpenJTalk for Japanese phonemization and produces natural prosody with context-dependent phoneme variants.

pip not recognized?

If pip is not found, try py -3.11 -m pip install piper-plus to target your Python 3.11 installation directly.

Help me fix pip not being recognized in PowerShell

• Download the tsukuyomi-chan Japanese neural model by running:

piper --download-model tsukuyomi

This downloads the pre-trained Japanese voice model to your local piper model cache.

• Generate a test audio file with Japanese speech by running:

piper --model tsukuyomi --text "いち、に、さん。りんご。おかあさん。" --output_file test_jp.wav

What does this test?

This generates a WAV file speaking numbers, a fruit, and a family word. These are typical Pre-N5 vocabulary items your videos will teach. Listen to test_jp.wav and compare the clarity and naturalness against the SAPI5 Haruka voice you tested earlier.

• Play the generated file by running:

Start-Process test_jp.wav

Compare this against the Haruka SAPI5 voice you heard earlier. The piper-plus tsukuyomi voice should sound noticeably more natural with smoother prosody.

Why piper-plus over SAPI5?

SAPI5 voices use concatenative synthesis from the early 2010s. piper-plus uses a neural architecture that produces natural pitch contours and timing. For a child's language acquisition, natural prosody matters because children learn intonation patterns alongside vocabulary.

Your primary voice for all video production will be piper-plus tsukuyomi. SAPI5 voices remain available as a fallback or for dual-voice scenarios (Format 3 whiteboard videos).

• Create your project working directory by running these commands:

cd ~/Desktop
mkdir bilingual-kids
cd bilingual-kids

• Confirm the directory exists by running:

Get-Location

You should see a path ending in bilingual-kids confirming you are inside your new project root.

mkdir failed with an error?

If Windows Controlled Folder Access blocks the command, open Windows Security then Virus & threat protection then Manage ransomware protection. Add PowerShell as an allowed app under Controlled Folder Access.

Help me fix mkdir failing in PowerShell on Windows

Your environment is locked in. Every runtime passes, your GPU is confirmed, and piper-plus delivers natural Japanese speech. Next up, you will configure MCP and deploy parallel agents to scaffold your entire vault and repository.

Build Parallel Agent Infrastructure (MCP, Vault, and Repo)

Your tools are verified and your working directory is ready. Now you need to give Claude Desktop the ability to read files, manage Git repositories, query databases, and crawl the web on your behalf.

The Model Context Protocol (MCP) is what makes this possible. By configuring MCP servers, Claude Desktop gains direct access to your filesystem, Git, SQLite, and Firecrawl. Once connected, you will deploy Claude as parallel agents to scaffold the entire vault and repository structure in minutes.

In this step, get ready to:

• Configure four MCP servers (filesystem, git, sqlite, Firecrawl) in Claude Desktop.
• Scaffold the Obsidian vault with 26 agent templates, research sources, and curriculum files via Claude agents.
• Initialize the GitHub repository with documentation directories and service folders via Claude agents.

Configure MCP servers in Claude Desktop

MCP servers are lightweight processes that Claude Desktop launches to interact with external tools. You need four: one for reading and writing files, one for Git operations, one for SQLite queries, and one for web crawling via Firecrawl.

• Open the MCP configuration file by navigating to it in File Explorer. The path is:

%APPDATA%\Claude\claude_desktop_config.json

• Open this file in any text editor (Notepad, VS Code, etc.).
• Replace the entire contents of the file with the following configuration:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:/Users/YOUR_USERNAME/bilingual-kids"]
    },
    "git": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git"]
    },
    "sqlite": {
      "command": "npx",
      "args": ["mcp-server-sqlite", "--db", "C:/Users/YOUR_USERNAME/bilingual-kids/pipeline.db"]
    },
    "firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "your-firecrawl-api-key-here"
      }
    }
  }
}

What does this configuration do?

• filesystem gives Claude read/write access to your bilingual-kids project folder via the @modelcontextprotocol/server-filesystem package.
• git lets Claude initialize repos, commit, and manage branches via @modelcontextprotocol/server-git.
• sqlite gives Claude a local database for pipeline state tracking.
• firecrawl enables web scraping and search for quarterly source freshness checks using your Firecrawl API key.

Replace YOUR_USERNAME with your Windows username

The filesystem path must point to your actual bilingual-kids directory. Open a terminal and run echo %USERPROFILE% to see your user folder path. Replace the forward slashes as needed.

• Save the file.
• Fully close Claude Desktop (check the system tray and right-click to quit).
• Reopen Claude Desktop.

After restarting, Claude Desktop loads the new MCP configuration. You should see a small hammer icon or MCP indicator in the Claude chat interface confirming the servers are connected.

MCP servers not connecting?

• If you see a spawn npx ENOENT error, Node.js is not in your system PATH. Open Command Prompt and run where npx to find the full path, then use that full path (e.g. C:\\Program Files\\nodejs\\npx.cmd) as the command value instead of npx.
• If a server shows as disconnected, verify the file paths in your config use forward slashes or properly escaped backslashes.
• If the FIRECRAWL_API_KEY is invalid, the firecrawl server will fail silently. Confirm your key at the Firecrawl dashboard.

help me troubleshoot my MCP server connection in Claude Desktop on Windows

Deploy Claude agents to scaffold the Obsidian vault

With MCP active, Claude can now create files directly in your project folder. You will give Claude a single prompt that instructs it to scaffold the entire Obsidian vault structure. This includes 26 agent prompt templates, research source directories, and curriculum planning files.

• In Claude Desktop, start a new conversation.
• Paste the following prompt to deploy the vault scaffolding agent:

You are the Vault Scaffolding Agent. Using the filesystem MCP server, create the following structure inside the bilingual-kids directory:

## Obsidian Vault Structure

Create a folder called `vault/` with these contents:

### Agent Templates (vault/agents/)
Create 26 Markdown files, one per agent:
- Team A (Curriculum): A1-jlpt-scope.md, A2-comprehensible-input.md, A3-repetition-routine.md, A4-age-band.md, A5-cultural-bridge.md
- Team B (Linguistic): B1-kana-kanji-validator.md, B2-furigana-annotator.md, B3-pronunciation-lexicon.md, B4-native-register-validator.md
- Team C (Visual): C1-manim-stroke.md, C2-remotion-compositor.md, C3-inkscape-svg.md, C4-brand-kit.md, C5-focal-element.md
- Team D (Audio): D1-voice-director.md, D2-ssml-engineer.md, D3-music-composer.md, D4-brand-sting.md
- Team E (Quality): E1-aap-advisor.md, E2-coppa-compliance.md, E3-eu-ai-act.md, E4-fact-verification.md
- Team F (Family): F1-onboarding.md, F2-co-viewing-guide.md, F3-retention-tracker.md, F4-brand-pricing.md

Each agent template should include:
- Agent ID and name
- Team assignment
- Role description
- Input/output contract
- Canonical data sources (from DATA-SOURCES.md)
- Self-improvement section (metrics to track, improvement triggers, version history)

### Research Sources (vault/07-RESEARCH/sources/)
Create placeholder files for:
- jlpt-official.md (www.jlpt.jp)
- japan-foundation.md (jpf.go.jp)
- nhk-easy-japanese.md (www3.nhk.or.jp)
- kuhl-phoneme-acquisition.md
- krashen-comprehensible-input.md
- asher-tpr.md
- blues-clues-repetition-model.md
- japanese-kindergarten-practices.md

### Curriculum Files (vault/)
Create these YAML/MD files:
- cultural-moments.yaml - Map vocabulary themes (numbers, fruits, colors, family, animals, body-parts) to authentic Japanese contexts (morning routine, seasonal market, nature walk, osechi preparation, zoo visit, bath time)
- curriculum-ladder.yaml - Spaced repetition scheduler with Pre-N5 through N1 levels, episode tracking, review intervals
- engagement-framework.md - Document Blue's Clues 3x repetition, anticipation pacing, multimodal redundancy, direct address, musical mnemonics
- cell.yaml - Age band definitions: 14mo-2yr, 2-3yr, 3-5yr, 5-7yr, 7-10yr, 10-14yr, 14yr+
- safety-checklist.yaml - AAP screen time, COPPA, WCAG 2.2 AA contrast >=7:1, no flashing, volume limits, EU AI Act Art 50

Create all files now. Use meaningful placeholder content that documents the PURPOSE of each file.

Why deploy via prompt instead of manual file creation?

Creating 40+ files manually would take significant time. Claude uses the filesystem MCP server to write all files in seconds. This is the parallel agent pattern in action. While Claude scaffolds, you can review the output incrementally as files appear in your project folder.

• Wait for Claude to finish creating files. You will see it calling the filesystem MCP tools in the chat.
• Verify the vault structure exists by running this in your terminal:

ls ~/bilingual-kids/vault/agents/

You should see 26 Markdown files listed (A1 through F4).

• Verify the curriculum files by running:

ls ~/bilingual-kids/vault/

You should see cultural-moments.yaml, curriculum-ladder.yaml, engagement-framework.md, cell.yaml, and safety-checklist.yaml in the output.

Missing files or empty vault folder?

• Check that the filesystem MCP server path in your config points to the correct bilingual-kids directory.
• If Claude reports a permission error, ensure your user account has write access to the folder.
• If only some files were created, re-run the prompt. Claude may hit a context limit on very long outputs. Ask it to continue from where it stopped.

help me figure out why Claude's filesystem MCP server cannot write files to my bilingual-kids directory

Initialize the GitHub repository via agent

The Obsidian vault holds your agent prompts and research. The GitHub repository holds the implementation code, architecture decision records, and pipeline services. You will now prompt Claude to scaffold the repo structure using the Git MCP server.

• In the same Claude Desktop conversation (or a new one), paste this prompt:

You are the Repository Scaffolding Agent. Using the filesystem and git MCP servers, create and initialize a Git repository inside bilingual-kids/repo/ with this structure:

## Directory Structure

### Documentation
- docs/adr/ (architecture decision records - create empty ADR-001 through ADR-011 placeholder files)
- docs/diagrams/ (Mermaid diagram files)
- docs/impl-plans/ (implementation plans per agent team)
- docs/style-references.md (reference video analysis notes)

### Service Directories (6 total)
- services/curriculum-engine/
- services/voice-synthesis/
- services/visual-compositor/
- services/quality-gate/
- services/engagement-optimizer/
- services/delivery-pipeline/

Each service directory should have a README.md describing its purpose.

### Root Files
- DATA-SOURCES.md - List all canonical sources (JLPT www.jlpt.jp, Japan Foundation jpf.go.jp, NHK WORLD www3.nhk.or.jp, Kuhl PNAS 2003, Krashen 1982, Asher 1969, AAP 2016+2024, COPPA, WCAG 2.2, EU AI Act)
- SELF-IMPROVEMENT.md - Document the self-improvement loop: lowest council scores trigger prompt refinement, operator approves diffs, version increments
- FIRECRAWL-SCHEDULE.md - Quarterly crawl targets: JLPT, NHK, AAP, Japan Foundation. Document the schedule and update process.
- cultural-moments.yaml - Copy from vault (maps themes to cultural contexts)
- engagement-framework.md - Copy from vault (Blue's Clues model documentation)
- safety-checklist.yaml - Copy from vault (compliance requirements)

### Git Initialization
- Initialize the repo with git init
- Create an initial commit with message "scaffold: initial project structure"
- Add a .gitignore for Python, Node.js, and common IDE files

Create all files and initialize the repository now.

Why separate vault and repo?

The Obsidian vault is your agent knowledge base. It contains prompt engineering, research notes, and planning documents that evolve through Obsidian's linking and plugin ecosystem.

The Git repository holds implementation code and architecture decisions that need version control, CI/CD, and collaboration features. Keeping them separate lets each tool do what it does best.

• Wait for Claude to finish. You will see it creating directories and files via the filesystem MCP, then initializing Git.
• Verify the repository structure by running:

ls ~/bilingual-kids/repo/

You should see docs/, services/, DATA-SOURCES.md, SELF-IMPROVEMENT.md, FIRECRAWL-SCHEDULE.md, and the other root files.

• Verify Git was initialized by running:

cd ~/bilingual-kids/repo && git log --oneline

You should see at least one commit with the message scaffold: initial project structure.

• Verify the 6 service directories exist:

ls ~/bilingual-kids/repo/services/

You should see curriculum-engine, voice-synthesis, visual-compositor, quality-gate, engagement-optimizer, and delivery-pipeline.

Git init failed or no commit showing?

• If Claude could not run git init, the Git MCP server may not be connected. Check your claude_desktop_config.json and restart Claude Desktop.
• If the commit failed, Claude may need you to configure Git identity first. Run git config --global user.name and git config --global user.email in your terminal to set these.

help me debug why the Git MCP server cannot initialize a repository in my project folder

Your parallel agent infrastructure is live. Claude Desktop can now read files, write code, manage Git, query databases, and crawl the web. The vault holds your 26 agent prompts and curriculum planning. The repo holds your implementation structure. Next, you will install the 26-agent council itself.

Install the 26-Agent Council with Cultural Heritage and Self-Improvement

Your vault is scaffolded, your MCP servers are live, and your repo has structure. Now comes the core of the system: 26 specialized agents that collectively turn a single theme word into a JLPT-aligned, culturally immersive bilingual video.

Each agent is a Markdown prompt template in your Obsidian vault. Together they form a council where no agent works alone. Team A designs curriculum. Team B validates language accuracy. Team C builds visuals. Team D produces audio. Team E enforces safety. Team F handles family engagement. Every single agent includes a self-improvement section that tracks what worked and refines itself after each episode.

In this step, get ready to:

• Install Team A (Curriculum + Pedagogy) and Team B (Linguistic Accuracy) with cultural bridge and register validation.
• Install Team C (Visual + Motion) and Team D (Audio + Voice) with cultural scene integration and engagement pacing.
• Install Team E (Quality + Safety) and Team F (Family Engagement + Brand) with compliance standards and co-viewing cultural talking points.

Install Team A (Curriculum + Pedagogy) and Team B (Linguistic Accuracy)

Team A designs what the child learns. Team B validates that every Japanese word, reading, and cultural reference is accurate. Together they ensure vocabulary is JLPT-scoped, delivered at the right developmental level, and always taught inside an authentic cultural moment.

• Switch to your Claude Desktop chat window.
• Deploy Team A and Team B by pasting the following prompt into Claude Desktop:

# Deploy Agent Teams A + B

Using the filesystem MCP, create the following agent prompt templates in the Obsidian vault's agent templates directory. Each template is a Markdown file with the structure shown below.

## Team A: Curriculum + Pedagogy (5 agents)

### A1 - JLPT Scope Strategist
- Role: Scope all vocabulary to appropriate JLPT level (Pre-N5 through N1)
- Source: www.jlpt.jp/e/about/levelsummary.html + test composition page
- Rules: Every word must map to a JLPT level. Pre-N5 for 14mo-3yr. N5 for 3-6yr.
- Self-improvement: Track vocabulary retention signals. If a word consistently fails engagement threshold, flag for re-scoping.

### A2 - Comprehensible Input Architect
- Role: Apply Krashen's i+1 hypothesis. New words = current level + 1 stretch item.
- Source: Krashen 1982 "Principles and Practice in SLA"
- Rules: 3x repetition minimum per new word. Context before isolation. Cultural moment first, word second.
- Self-improvement: Track i+1 calibration. If parent reports confusion, adjust difficulty delta.

### A3 - Repetition-Routine Designer
- Role: Design spaced repetition across episodes using Blue's Clues model.
- Source: Blue's Clues research (3x episode repetition) + engagement-framework.md
- References: curriculum-ladder.yaml for cross-episode scheduling
- Rules: Each new word appears 3x within episode, resurfaces in next 2 episodes.
- Self-improvement: Analyze which repetition patterns correlate with parent-reported recall.

### A4 - Age-Band Calibrator
- Role: Calibrate content to developmental stage per Kuhl + AAP.
- Source: Patricia Kuhl PNAS 2003/2017 (phoneme window), AAP 2016+2024 screen-time
- Rules: 14-18mo = single words + high contrast + <2min segments. 3-5yr = short phrases + narrative. 6+ = sentences + reading.
- Self-improvement: As child ages, auto-suggest curriculum-ladder.yaml updates.

### A5 - Cultural Bridge Designer
- Role: Ensure every vocabulary set is taught inside an authentic Japanese cultural moment.
- Source: cultural-moments.yaml + Japanese kindergarten practices
- Rules: Numbers = morning routine counting (steps to genkan, rice bowls). Fruits = seasonal market visit. Colors = nature walk. Family = osechi preparation.
- Cultural practices referenced: Tanabata, itadakimasu, o-soji, origami, genkan, ofuro
- Self-improvement: Track which cultural contexts produce highest engagement. Prioritize effective contexts for future episodes.

## Team B: Linguistic Accuracy (4 agents)

### B1 - Kana + Kanji Validator
- Role: Validate all kana/kanji against JLPT character sets
- Source: JLPT character sets + Japan Foundation Memory Hint apps
- Rules: No kanji above target JLPT level. All kanji have furigana. Stroke order matches standard.
- Self-improvement: Log any validator-caught errors. Identify recurring mistake patterns in generation.

### B2 - Furigana Annotator
- Role: Generate and validate furigana readings for all Japanese text
- Source: PyKakasi + SudachiPy cross-check against JLPT scope
- Rules: Every kanji gets furigana. Readings match NHK standard pronunciation.
- Self-improvement: Track edge cases where PyKakasi and SudachiPy disagree. Build exception list.

### B3 - Pronunciation Lexicon Owner
- Role: Maintain canonical pronunciation for all vocabulary
- Source: NHK pronunciation dictionary (standard Tokyo dialect)
- Rules: Pitch accent marked. Long vowels explicit. Gemination noted.
- Self-improvement: When piper-plus synthesis sounds wrong, log and add to override lexicon.

### B4 - Cultural Register Validator
- Role: Validate cultural authenticity. "Is this how a Japanese parent would actually teach this?"
- Source: NHK E-tele Nihongo de Asobo + NHK WORLD Easy Japanese
- References: cultural-moments.yaml for context validation
- Rules: Reject anything that feels "textbook" rather than natural. Validate against real Japanese parenting patterns.
- Self-improvement: Collect native-speaker feedback on register. Update validation criteria quarterly.

What does this prompt do?

This instructs Claude to create 9 Markdown files (one per agent) in your Obsidian vault via the filesystem MCP server. Each file defines the agent's role, canonical sources, operating rules, and self-improvement hooks.

A5 (Cultural Bridge) is the keystone agent. It ensures vocabulary never appears in a vacuum. When the theme is "numbers," A5 maps it to a Japanese morning routine where a child counts steps to the genkan. This is what separates flashcard-style teaching from cultural immersion.

What is JLPT?

The JLPT (Japanese Language Proficiency Test) is the internationally recognized standard for Japanese as a foreign language, administered by the Japan Foundation and JEES. It has 5 levels from N5 (basic) to N1 (advanced). Your pipeline adds a Pre-N5 tier for toddlers below N5 readiness.

• Wait for Claude to confirm all 9 template files have been created via MCP.
• Switch to your Obsidian vault and verify that 9 new Markdown files appear in your agent templates directory (A1 through A5, B1 through B4).
• Open any template (try A5) and confirm it has the Role, Source, Rules, and Self-improvement sections populated.

Templates not appearing in Obsidian?

Make sure the filesystem MCP server in your claude_desktop_config.json points to the correct vault path. Claude can only write to directories listed in the MCP server's allowed paths.

If Obsidian shows the files but they appear empty, click into one and give it a moment to sync. Large batch file creation can take a few seconds to propagate in the vault index.

Help me troubleshoot why Claude's MCP filesystem server isn't writing files to my Obsidian vault.

Install Team C (Visual + Motion) and Team D (Audio + Voice)

Team C produces everything the child sees. Team D produces everything the child hears. Cultural context flows through both: C3 draws genkan scenes and sakura parks, while D3 composes pentatonic music aligned with Japanese children's media like Okaasan to Issho.

• In your Claude Desktop chat, deploy Teams C and D by pasting the following prompt:

# Deploy Agent Teams C + D

Using the filesystem MCP, create the following agent prompt templates in the Obsidian vault's agent templates directory.

## Team C: Visual + Motion (5 agents)

### C1 - Manim Stroke-Order Animator
- Role: Generate kana/kanji stroke-order animations using Manim Community
- Output: MP4 clips showing correct stroke order with timing markers
- Rules: One character per clip. Stroke direction arrows. Playback speed matched to age band.
- Self-improvement: Track which stroke-order styles (dotted guide vs clean) produce better parent feedback.

### C2 - Remotion Engagement Pacer
- Role: Control Remotion composition timing for maximum child engagement
- Source: engagement-framework.md
- Rules: Mascot eye-contact (2s) → anticipation build (1.5s) → reveal (0.5s) → 3x repetition (3s each) → musical mnemonic (4s). One focal element per frame. No scene longer than 15s for under-3.
- Self-improvement: Log per-scene engagement duration estimates. Adjust pacing ratios based on completion data.

### C3 - Inkscape SVG Cultural Scene Designer
- Role: Create SVG assets for culturally authentic Japanese environments
- Assets include: genkan (entrance), dining table with chopsticks, sakura park, seasonal market, family room with kotatsu, tatami room, torii gate, noren curtains, bento box
- Rules: Child-friendly color palette. High contrast (>=7:1 WCAG). Simple shapes. Cultural accuracy verified by B4.
- Self-improvement: Track which scene types correlate with higher engagement. Expand effective scene library.

### C4 - Brand Kit Manager
- Role: Maintain visual coherence across all episodes and formats
- Assets: Color palette (culturally coherent), typography (JP: rounded gothic, EN: friendly sans), mascot variants, transition library
- Rules: Consistent across all 3 output formats. Seasonal palette shifts (spring pastels, summer brights, autumn warm, winter cool).
- Self-improvement: A/B test palette variations across episodes. Converge on highest-engagement brand elements.

### C5 - Focal Element Enforcer
- Role: Ensure one clear visual focal point per frame
- Rules: Single subject per scene. Background at 30% opacity max. Motion draws eye to learning target. No competing visual elements.
- Self-improvement: Flag frames with multiple competing elements. Track correlation between focal clarity and repetition recall.

## Team D: Audio + Voice (4 agents)

### D1 - Voice Director (piper-plus Primary)
- Role: Direct all Japanese voice synthesis using piper-plus with tsukuyomi model
- Fallback: SAPI5 Haruka for comparison/backup
- Rules: Rate 0.85-0.92 for Pre-N5/N5. Clear articulation. Warm tone. 250-400ms pause between EN-JP language pairs.
- Self-improvement: Compare piper-plus vs SAPI5 Haruka clarity per word. Build preferred-voice-per-context map.

### D2 - SSML Engagement Timer
- Role: Generate SSML markup for voice timing aligned with engagement pacing
- Rules: Match C2 timing. Anticipation pause before reveal. Emphasis on new vocabulary. Rate slowdown on first introduction, normal on repetitions 2-3.
- Self-improvement: Correlate SSML timing variations with engagement estimates. Optimize pause durations.

### D3 - Music Composer (Pentatonic)
- Role: Compose background music using Japanese pentatonic scale
- Style: Okaasan to Issho gentle tone. Culturally aligned instrumentation.
- Rules: Ducked -18dB under voice. Pentatonic melody. Tempo matched to age band (slower for younger). Musical mnemonic per vocabulary word.
- Self-improvement: Track which melodic patterns correlate with vocabulary recall. Build mnemonic effectiveness library.

### D4 - Brand Sting Producer
- Role: Create and maintain audio brand identity
- Output: 3-second opening sting + 2-second closing sting (Audacity)
- Rules: Japanese-inspired audio motif. Pentatonic. Recognizable within 3 notes. Consistent across all episodes.
- Self-improvement: Test sting variations for brand recognition. Lock in highest-recognition version after 5 episodes.

What does this prompt do?

This creates 9 more agent templates (C1 through C5, D1 through D4). C2 and D2 work as a pair: C2 controls visual timing while D2 synchronizes voice to match. The engagement-framework.md you created earlier is the shared reference both use.

D1 uses piper-plus with the tsukuyomi model as the primary Japanese voice. The SAPI5 voices (Haruka, Ichiro, Ayumi) serve as fallback and comparison baseline.

• Wait for Claude to confirm all 9 template files are created.
• In Obsidian, verify C1 through C5 and D1 through D4 now appear in your agent templates directory.
• Open C3 (Inkscape SVG Cultural Scene Designer) and confirm the cultural assets list includes genkan, sakura park, and seasonal market.

Why pentatonic music?

The pentatonic scale (five-note scale) is foundational to traditional Japanese music. Children's programs like Okaasan to Issho use it extensively. D3 composes in this scale so the background music feels culturally coherent. The child absorbs not just vocabulary but the musical texture of Japanese culture.

Claude stopped mid-generation?

If Claude's response was cut off before confirming all 9 files, type "continue" to resume. Claude Max 20x sessions can handle long outputs but occasionally hit display limits.

If MCP writes fail silently, check Claude's response for error mentions. The filesystem server logs to stderr, visible in the Claude Desktop developer console.

Help me debug Claude Desktop cutting off mid-response when creating multiple agent template files via MCP.

Install Team E (Quality + Safety) and Team F (Family Engagement + Brand)

Team E is the guardrail layer. Every video must pass AAP screen-time compliance, COPPA requirements, EU AI Act transparency rules, and fact verification before reaching a child. Team F ensures the parent is an active participant, not a passive screen-hander.

• In your Claude Desktop chat, deploy Teams E and F by pasting the following prompt:

# Deploy Agent Teams E + F

Using the filesystem MCP, create the following agent prompt templates in the Obsidian vault's agent templates directory.

## Team E: Quality + Safety (4 agents)

### E1 - AAP Screen-Time Advisor
- Role: Enforce AAP 2016 + 2024 screen-time guidance per age band
- Source: AAP policy statement 2016, AAP 2024 update
- Rules: Under 18 months = video chat only (our content is co-viewed, parent-mediated exception). 18-24mo = high-quality, co-viewed, max 2 min segments. 2-5yr = max 1hr/day high-quality. All content requires co-viewing guide.
- Flags: Any episode >5min for under-3. Any content without co-viewing guide. Any content designed for solo viewing under 2.
- Self-improvement: Track AAP guideline updates. Flag when new research shifts recommendations.

### E2 - COPPA Compliance Officer
- Role: Ensure all content and delivery complies with COPPA (15 U.S.C. 6501-6506)
- Source: 15 U.S.C. 6501-6506 + YouTube Made-for-Kids requirements
- Rules: No data collection from children. No behavioral advertising signals. No interactive elements requiring child input. Content marked Made-for-Kids compatible.
- Self-improvement: Monitor FTC enforcement actions. Update checklist when new COPPA guidance issued.

### E3 - EU AI Act Transparency Agent
- Role: Ensure AI-generated content meets EU AI Act Art 50 transparency requirements
- Source: EU AI Act Article 50 (effective 2 Aug 2026)
- Rules: AI-generated content clearly labeled. Metadata includes generation method. Parent informed which elements are AI-produced. No deepfake-adjacent content.
- Self-improvement: Track EU AI Act implementation guidance as it develops post-August 2026.

### E4 - Fact Verification Coordinator
- Role: Coordinate cross-model fact-checking (Claude generates, Codex reviews)
- Process: All Japanese facts → Codex adversarial review → Claude validates Codex output → disagreements → human operator
- Sources verified: JLPT accuracy, pronunciation, cultural accuracy, NHK register, AAP compliance, spaced-repetition correctness
- Rules: Zero tolerance for unverified Japanese language facts. Every cultural claim traceable to canonical source.
- Self-improvement: Track verification failure patterns. Pre-screen known problem areas in generation prompts.

## Team F: Family Engagement + Brand (4 agents)

### F1 - Family Onboarding Designer
- Role: Design family onboarding flow for new clients
- Output: Welcome sequence, expectation setting, co-viewing training, progress tracking setup
- Rules: Parent understands their role (co-viewer, not screen-hander). Cultural context explained. Realistic expectations set.
- Self-improvement: Track onboarding completion rates. Simplify steps with high drop-off.

### F2 - Co-Viewing Guide Author
- Role: Write episode-specific co-viewing guide with cultural talking points
- Output: Per-episode PDF/Markdown with vocabulary list, cultural context, suggested activities
- Rules: Include cultural talking points ("After watching, try saying itadakimasu together at dinner."). Suggest real-world reinforcement activities. Connect vocabulary to family's daily life.
- Self-improvement: Track which talking points parents report using. Double down on effective formats.

### F3 - Retention + Cultural Connection Tracker
- Role: Track engagement signals and cultural connection depth across episodes
- Metrics: Episode completion, vocabulary recall (parent-reported), cultural moment recognition, re-watch requests
- Rules: Spaced repetition validated against actual retention. Cultural contexts that fail engagement get replaced.
- Self-improvement: Build predictive model of which cultural contexts produce best retention per age band.

### F4 - Brand + Pricing Strategist
- Role: Maintain brand coherence and pricing model
- Model: Per-video delivery, theme-triggered by client
- Rules: Consistent quality bar. Clear deliverable scope. Transparent about AI involvement (per E3).
- Self-improvement: Track client satisfaction. Adjust deliverable scope based on feedback patterns.

What does this prompt do?

This creates the final 8 agent templates (E1 through E4, F1 through F4). E4 is the bridge between Claude and Codex. It defines the adversarial review process where Codex independently checks every Japanese fact Claude generates.

F2 is what makes this system parent-friendly. Every episode ships with a co-viewing guide that gives parents cultural talking points. The parent doesn't need to know Japanese grammar. They just need the guide's suggestion: "After watching, try saying itadakimasu together at dinner."

Why cross-model adversarial review?

If Claude generates Japanese content and Claude also reviews it, errors can pass undetected (echo-chamber bias). Codex operates independently on a different model architecture. When Codex flags a pronunciation or cultural claim, Claude must defend it against canonical sources or the content gets revised. Disagreements go to the human operator.

• Wait for Claude to confirm all 8 template files are created.
• In Obsidian, verify E1 through E4 and F1 through F4 now appear in your agent templates directory.
• Open F2 (Co-Viewing Guide Author) and confirm it includes the cultural talking points directive.
• Count all templates in the directory. You should now have 26 agent Markdown files total (A1-A5, B1-B4, C1-C5, D1-D4, E1-E4, F1-F4).

Only seeing 25 or fewer templates?

Check which agent file is missing by comparing against the full list: A1-A5 (5), B1-B4 (4), C1-C5 (5), D1-D4 (4), E1-E4 (4), F1-F4 (4). Ask Claude to create the missing template specifically by name.

If templates were created but lack self-improvement sections, ask Claude to append the Self-improvement section to each file. Every agent must have this section for the continuous learning loop to work.

Help me figure out which agent templates are missing from my vault and how to get Claude to create them.

Now instruct Claude to draft ADRs (Architecture Decision Records) for each team. These go in the GitHub repo.

• Ask Claude to create team ADRs in your repo by pasting this follow-up prompt:

# Draft ADRs for Each Agent Team

Using the git MCP server, create ADR files in docs/adr/ with the following:

- ADR-003-team-a-curriculum-pedagogy.md: Why 5 agents for curriculum. Why JLPT as standard. Why cultural bridge is separate from language teaching.
- ADR-004-team-b-linguistic-accuracy.md: Why 4 validators. Why PyKakasi + SudachiPy dual-check. Why cultural register needs its own agent.
- ADR-005-team-c-visual-motion.md: Why 5 visual agents. Why Remotion as compositor. Why SVG over raster for cultural scenes.
- ADR-006-team-d-audio-voice.md: Why piper-plus over SAPI5 as primary. Why pentatonic. Why separate brand sting.
- ADR-007-team-e-quality-safety.md: Why 4 safety agents. Why AAP/COPPA/EU AI Act each get dedicated agents. Why fact verification coordinates cross-model.
- ADR-008-team-f-family-engagement.md: Why co-viewing guide is non-negotiable. Why cultural talking points matter. Why retention tracks cultural connection separately.

Each ADR follows the format: Title, Status (Accepted), Context, Decision, Consequences.

What are ADRs?

Architecture Decision Records document why you made a design choice, not just what you chose. Six months from now when you wonder "why does cultural register need its own agent," ADR-004 has the answer. They live in docs/adr/ in your GitHub repo.

• Wait for Claude to confirm the 6 ADR files are created in docs/adr/.
• Verify by asking Claude to list the contents of docs/adr/ via the filesystem MCP. You should see the 6 new ADR files alongside any earlier ADRs from Step 2.

Your 26-agent council is installed. Each agent knows its role, its canonical sources, and how to improve itself over time. Next, you will wire these agents into a multi-stage pipeline with ADRs, Mermaid diagrams, and implementation plans that define how a single theme word flows through the entire council to produce a finished video.

Design the Multi-Stage Pipeline Architecture

Your 26 agents are installed and ready. Before they can execute in parallel, they need a shared architectural blueprint that defines how decisions were made, how the pipeline flows, and what each team is responsible for.

In this step, you will author Architecture Decision Records (ADRs) that capture the reasoning behind every major design choice. You will also create Mermaid diagrams that visualize the pipeline, and generate implementation plans that each team can execute independently.

In this step, get ready to:

• Author ADR-001 through ADR-011 with agent assistance, including the cultural heritage immersion rationale.
• Create six GitHub-flavored Mermaid diagrams covering the full pipeline architecture.
• Generate implementation plans per team with parallel execution readiness and success criteria.

Author ADRs with agent assistance

Architecture Decision Records capture the "why" behind each major design choice. When future-you (or a collaborator) asks "why piper-plus instead of SAPI5?" the ADR has the answer. Your 26 agents already have draft ADRs from the previous step. Now you will finalize all eleven.

• Switch back to Claude Desktop and paste this prompt to have Claude finalize the ADR suite:

Using the filesystem MCP, finalize ADR-001 through ADR-011 in docs/adr/.
Each ADR must follow the MADR format:
- Title, Status (Accepted), Date
- Context and Problem Statement
- Decision Drivers
- Considered Options (at least 2)
- Decision Outcome with justification
- Consequences (positive and negative)

The eleven ADRs are:
- ADR-001: Use MADR format for decision records
- ADR-002: piper-plus as primary JP TTS (over SAPI5 Haruka)
- ADR-003: Remotion as universal video compositor
- ADR-004: Three visual output formats (SVG motion, AI imagery, whiteboard)
- ADR-005: Codex as adversarial cross-model reviewer
- ADR-006: JLPT as curriculum standard (over Genki/Minna no Nihongo)
- ADR-007: Spaced repetition via curriculum-ladder.yaml
- ADR-008: Age-band calibration per AAP + Kuhl research
- ADR-009: MCP filesystem for local-first edit-as-code
- ADR-010: Firecrawl for quarterly source freshness checks
- ADR-011: Cultural heritage immersion (vocabulary inside cultural context
  produces deeper retention than isolated word learning)

For ADR-011, reference cultural-moments.yaml and cite:
- Japanese kindergarten practices (itadakimasu, o-soji, seasonal events)
- Kuhl/Krashen research on contextual language acquisition
- The project philosophy: language without culture is hollow

Commit all files to docs/adr/ via the git MCP server.

What is an ADR?

An Architecture Decision Record is a short Markdown document that captures one design decision, the options you considered, and why you chose the winner. ADRs live in version control alongside your code so the reasoning is never lost.

The MADR (Markdown Any Decision Records) format keeps each record lean. Context, drivers, options, outcome, consequences. One to two pages maximum.

• Wait for Claude to confirm all eleven ADR files are committed to docs/adr/.
• Verify ADR-011 specifically by asking Claude to display its contents. Confirm it references cultural-moments.yaml and cites the cultural immersion rationale.

Claude not finding docs/adr/?

The filesystem MCP server can only access directories listed in its config. Confirm that your project root is included in the allowedDirectories array inside claude_desktop_config.json.

If Claude says the git MCP server is unavailable, restart Claude Desktop. MCP servers sometimes fail to connect on first launch.

help me troubleshoot why Claude cannot access my docs/adr/ directory via MCP

Create six Mermaid diagrams for the pipeline

GitHub renders Mermaid diagrams natively inside Markdown files. You will create six diagrams that visualize how the pipeline works end-to-end. These live in docs/diagrams/ and render automatically when viewed on GitHub.

• Paste this prompt in Claude Desktop to generate all six diagrams:

Using the filesystem MCP, create 6 Mermaid diagram files in docs/diagrams/.
Each file is a .md Markdown file with a ```mermaid fenced code block.

1. pipeline-sequence.md - Theme-triggered pipeline sequence diagram
   Use sequenceDiagram. Participants: Client, Orchestrator, TeamA,
   TeamB, TeamC, TeamD, TeamE, TeamF, Codex, HumanGate.
   Flow: Client sends theme -> Orchestrator fans out to teams ->
   Teams produce artifacts -> Codex reviews -> HumanGate approves -> Delivery.

2. self-improvement-state.md - Self-improvement state machine
   Use stateDiagram-v2. States: Idle, Evaluating, ImprovementFound,
   DraftingFix, OperatorReview, Accepted, VersionIncremented.
   Show the loop from Evaluating back to Idle when no issues found.

3. age-adaptation-flow.md - Age-adaptation flowchart
   Use flowchart TD. Show how target-child-profile.yaml age drives
   selection of cell.yaml band (14mo, 2yr, 3yr, 5yr, 7yr, 10yr, teen, adult)
   and maps to JLPT level (Pre-N5 through N1).

4. curriculum-ladder-seasons.md - Curriculum ladder with cultural themes
   Use flowchart LR. Show vocabulary themes mapped to Japanese seasons:
   Spring (sakura, hanami, graduation), Summer (matsuri, tanabata, natsu-yasumi),
   Autumn (momiji, tsukimi, harvest), Winter (oshogatsu, setsubun, yuki).

5. engagement-pacing.md - Engagement pacing per episode
   Use sequenceDiagram. Participants: Timer, Visual, Audio, Child.
   Show the rhythm: Hook(0-15s) -> Teach(15-60s) -> Repeat1 ->
   Repeat2 -> Repeat3 -> Mnemonic -> Goodbye.

6. cultural-context-selection.md - Cultural context selection flow
   Use flowchart TD. Show: Theme input -> A5 Cultural Bridge queries
   cultural-moments.yaml -> Matches season? -> Selects context ->
   B4 validates cultural register -> Output: culturally-embedded script.

Commit all files to docs/diagrams/ via git MCP.

Why Mermaid for architecture diagrams?

Mermaid diagrams are text-based, which means they live in version control, diff cleanly, and render automatically on GitHub. No image files to maintain. When your pipeline changes, you update the text and the diagram updates with it.

GitHub supports sequenceDiagram, stateDiagram-v2, and flowchart syntax natively in any Markdown file.

• Wait for Claude to confirm all six diagram files are committed.
• Verify the diagrams render correctly by asking Claude to display the contents of docs/diagrams/pipeline-sequence.md. Confirm it contains a valid sequenceDiagram block with all participants listed.

Diagram syntax errors on GitHub?

Mermaid is sensitive to certain reserved words. If a diagram fails to render, check for unquoted use of the word "end" inside node labels. Wrap it in quotes to prevent breakage.

Also confirm each diagram file uses a fenced code block with the mermaid language identifier, not just raw Mermaid syntax.

help me fix my Mermaid diagram syntax errors

Generate implementation plans and style references

Each agent team needs a concrete plan that says what to build, in what order, and how to verify success. These plans enable parallel execution. Team C can build visual assets at the same time Team D prepares audio, because both plans reference the same shared script format.

• Paste this prompt in Claude Desktop to generate the implementation plans and style references:

Using the filesystem MCP, create implementation plans and style references:

1. In docs/impl-plans/, create one file per team (team-a-plan.md through
   team-f-plan.md). Each plan includes:
   - Team name and agent list
   - Responsibilities and deliverables
   - Dependencies on other teams (what they need as input)
   - Parallel execution notes (what can run independently)
   - Cultural authenticity checkpoint (how this team ensures cultural fidelity)
   - Success criteria with measurable metrics:
     * Engagement metrics (3x repetition confirmed, anticipation beats present)
     * Cultural fidelity metrics (A5 + B4 + Codex triple-check passes)
     * Technical metrics (WCAG >= 7:1 contrast, Whisper >= 95%, AAP compliant)

2. Create docs/style-references.md with 3 reference video recommendations:
   - Reference 1: NHK E-tele "Nihongo de Asobo" (にほんごであそぼ)
     Style: Playful kana exploration, cultural immersion, musical hooks
   - Reference 2: NHK E-tele "Okaasan to Issho" (おかあさんといっしょ)
     Style: Parent-child engagement, repetition, gentle pacing
   - Reference 3: "Shimajiro" (しまじろう) by Benesse
     Style: Character-led learning, sequential skill building, daily-life context
   For each, describe the visual style, pacing, engagement techniques,
   and what to adopt vs. what to adapt for bilingual heritage use.

Commit all files via git MCP.

Why parallel execution readiness matters

Without implementation plans, teams block each other. Team C waits for Team A's script, Team D waits for Team C's timing data, and nothing moves. The plans define shared interfaces (script format, timing JSON, caption SRT) so each team can start building immediately against a known contract.

The cultural authenticity checkpoint in each plan ensures that cultural fidelity is not an afterthought. Every team validates their output against cultural-moments.yaml before passing work downstream.

• Wait for Claude to confirm all implementation plan files and docs/style-references.md are committed.
• Verify the plans are complete by asking Claude to list the files in docs/impl-plans/. You should see six files: team-a-plan.md through team-f-plan.md.
• Confirm docs/style-references.md contains all three reference videos with style descriptions.

Plans missing cultural checkpoints?

If Claude generated plans without the cultural authenticity section, reply with: "Each plan needs a Cultural Authenticity Checkpoint section. Add it to all six plans and recommit." Claude will update the files in place.

help me ensure my implementation plans include cultural fidelity checkpoints

Your architecture is now documented. Every design decision has a rationale, every flow has a visual, and every team has a parallel execution plan. Next up, you will build the three-format video composition pipeline that turns council-approved scripts into actual video output.

Build the Three-Format Video Composition Pipeline

Your agents, architecture, and cultural content library are ready. Now it's time to build the actual video production machinery.

Three visual formats serve different learning moments and parental preferences. Each format wraps the same JLPT-aligned, culturally-contextual script in a different visual style. The learner (your client's daughter) gets the same vocabulary inside the same cultural moment, but the visual delivery changes.

In this step, get ready to:

• Build Format 1 (Remotion + SVG Motion Graphics) as the primary composition pipeline with cultural scenes, Manim kana, and piper-plus voice.
• Build Format 2 (Nano Banana Pro Image-Stitch) and Format 3 (InstaDoodle Whiteboard Sketch) pipelines.
• Wire shared infrastructure: furigana caption pipeline, ffmpeg finalization, Playwright HTML-to-PNG, and openai-whisper validation.

Build Format 1: Remotion + SVG Motion Graphics

Format 1 is the primary pipeline. It combines programmatic video composition in Remotion with Manim-rendered kana stroke-order animations, hand-crafted SVG cultural scenes, neural Japanese voice via piper-plus, and pentatonic music. Every frame has one focal element. The engagement sequence follows: mascot eye-contact, anticipation, reveal, 3x repetition, musical mnemonic.

• Scaffold the Remotion project inside services/remotion-svg/ by running:

cd services/remotion-svg
npx create-video@latest

What does this scaffold?

Remotion v4.0.465 creates a React/TSX project purpose-built for programmatic video. You get src/Root.tsx, src/Composition.tsx, and a public/ directory for static assets (SVGs, audio files). The free license covers individuals and teams up to 3 people with unlimited renders.

• Deploy your Claude agent (via MCP) to build the Format 1 composition pipeline. Give Claude this instruction in a new conversation:

# Format 1 Build: Remotion + SVG Motion Graphics

Using the implementation plan in docs/impl-plans/ and cultural-moments.yaml, build the Format 1 pipeline in services/remotion-svg/:

## Cultural Scene Compositions (TSX)
- Create compositions with engagement sequence: mascot eye-contact → anticipation → reveal → 3x repetition → musical mnemonic
- One focal element per frame (never split attention)
- Scenes set in authentic Japanese environments referenced in cultural-moments.yaml

## SVG Cultural Scene Library (services/inkscape-svgs/)
- Create SVG assets for: genkan, dining table, sakura park, torii, noren, tatami, bento
- Each SVG optimized for Remotion rendering (clean paths, no embedded fonts)
- Child-friendly proportions, high contrast (>=7:1 WCAG)

## Manim Kana Stroke-Order (services/manim/)
- Create Manim Community scripts for hiragana/katakana stroke-order animations
- Output as MP4 clips that Remotion imports via <OffthreadVideo>
- Start with Pre-N5 kana set

## Audio Integration
- piper-plus tsukuyomi voice: configure synthesis pipeline
- Pentatonic music bed (royalty-free, ducked -18dB under voice)
- Brand sting audio placement at intro/outro

## Furigana Captions
- Integrate PyKakasi + SudachiPy + fugashi for furigana annotation
- Generate styled <div> captions with ruby text
- Position: bottom-safe area, high-contrast background

Commit all to the GitHub repo under the appropriate service directories.

Why three Japanese text tools?

PyKakasi converts kanji to kana readings. SudachiPy provides morphological analysis (word boundaries). fugashi wraps MeCab for accent and part-of-speech data. Together they produce accurate furigana annotations that respect word boundaries.

• While the agent builds, verify piper-plus voice integration by synthesizing a test cultural phrase:

piper --model tsukuyomi --text "いち、に、さん。りんご。おかあさん。" --output_file test_jp.wav

• Confirm the WAV file plays clearly and you can hear each word distinctly separated. This is the voice your videos will use.

Agent not finding cultural-moments.yaml?

Make sure the filesystem MCP server in your claude_desktop_config.json has the project root in its allowed directories. The agent needs read access to reference cultural-moments.yaml when building compositions.

help me debug why my Claude agent can't access cultural-moments.yaml via MCP filesystem

Build Format 2 and Format 3 pipelines

Format 2 uses Nano Banana Pro (Gemini 3 Pro Image Preview) to generate culturally-specific illustrations stitched together with Ken Burns motion in Remotion. Format 3 uses InstaDoodle whiteboard animations with dual-voice SAPI5 narration. Both formats reuse the same JLPT-aligned script and caption pipeline from Format 1.

• Deploy Claude to build the Format 2 pipeline. Give Claude this instruction:

# Format 2 Build: Nano Banana Pro Image-Stitch

Build the Format 2 pipeline in services/image-stitch/:

## Culturally-Specific Image Prompt Templates (services/image-stitch/prompts/)
- Create prompt templates that specify Japanese cultural context
- NOT generic: "Bright red apple in wooden basket at Japanese autumn market, maple leaves, child-friendly illustration"
- Each prompt references cultural-moments.yaml for authentic scene context
- Include: season, setting, cultural elements, child-friendly style directives
- Target model: gemini-3-pro-image-preview (Nano Banana Pro)

## Remotion Ken Burns Composition (services/image-stitch/)
- Scaffold Remotion composition for image sequences
- Ken Burns effect: scale + translateX interpolation over 15-20sec per image
- <Transition> crossfades between scenes
- piper-plus tsukuyomi voice track integration
- Caption overlays (same pipeline as Format 1)
- High contrast, single focal element per frame
- Multimodal pairing: voice names object as it appears visually

## Image Generation Workflow
- Batch generation script (respects Google AI Pro 5-hour refresh cycle)
- Download and organize images by episode/scene
- Estimated: 15-20 images per 5-minute video (15-20 seconds display each)

Commit to GitHub repo.

Why batch image generation?

Google AI Pro usage limits refresh every 5 hours with a weekly cap. Nano Banana Pro has its own images-per-minute rate limit separate from text tokens. Batch all image generation prompts for a single episode in one session to avoid hitting refresh boundaries mid-production.

• Deploy Claude to build the Format 3 pipeline. Give Claude this instruction:

# Format 3 Build: InstaDoodle Whiteboard Sketch

Build the Format 3 pipeline in services/instadoodle/:

## Culturally-Themed Scene Scripts (services/instadoodle/)
- Convert council-approved scripts into InstaDoodle scene format
- Reveals draw Japanese cultural elements: chopsticks, rice bowl, cherry tree
- Mimic parent sketching at kitchen table (intimate, warm tone)
- One element revealed at a time (engagement: reveal pacing)
- DoodleAI engine handles whiteboard animation generation

## Remotion Dual-Voice Composition (services/instadoodle/)
- Scaffold Remotion composition for whiteboard clips
- Whiteboard MP4 clips as <OffthreadVideo> segments
- Dual-voice SAPI5: Haruka (Japanese) + Zira (English), alternating
- SSML rate 0.85-0.92 with 250-400ms breaks between EN-JP pairs
- Caption overlays (same pipeline as Format 1)
- Hand-reveal pacing matched to voice timing

## Export Verification
- Verify InstaDoodle 16:9 output compatibility
- Confirm Remotion can import whiteboard clips cleanly

Commit to GitHub repo.

Why dual-voice for Format 3?

The whiteboard format mimics a parent drawing at the kitchen table. Dual-voice (Haruka for Japanese, Zira for English) creates a bilingual narrative flow. The 250-400ms pause between language pairs gives the toddler time to process each word before hearing its translation.

• Verify both Format 2 and Format 3 directories exist and contain the expected files by running:

ls services/image-stitch/prompts/
ls services/instadoodle/

• You should see prompt template files in services/image-stitch/prompts/ and scene scripts in services/instadoodle/.

InstaDoodle export resolution concerns?

InstaDoodle Pro exports at 4K resolution. Verify the output is 16:9 aspect ratio before building your Remotion composition. If the aspect ratio differs, add a letterboxing or cropping step in the Remotion sequence.

help me configure InstaDoodle exports for Remotion compatibility

Wire shared infrastructure: captions, ffmpeg, Playwright, and whisper validation

All three formats depend on the same backbone: a furigana caption pipeline that annotates Japanese with readings, ffmpeg for final muxing, Playwright for rendering HTML caption overlays to PNG, and openai-whisper for round-trip caption validation (target: 95% accuracy).

• Install the caption pipeline dependencies by running:

pip install pykakasi sudachipy fugashi openai-whisper

What does each package do?

• pykakasi: Converts kanji to hiragana/katakana readings for furigana overlay.
• sudachipy: Morphological analyzer that identifies word boundaries accurately (critical for placing furigana on the correct characters).
• fugashi: MeCab wrapper providing part-of-speech and accent data for natural reading generation.
• openai-whisper: Speech-to-text model that validates captions match actual audio. Target: 95% round-trip accuracy.

• Install Playwright for HTML-to-PNG caption rendering by running:

cd services/playwright
npm install -D @playwright/test@latest
npx playwright install

• Deploy Claude to wire the remaining shared infrastructure. Give Claude this instruction:

# Shared Infrastructure Build

Wire the shared backbone that all three formats depend on:

## Furigana Caption Pipeline (configured across all formats)
- PyKakasi + SudachiPy + fugashi working together
- Input: Japanese script text
- Output: HTML with <ruby> furigana annotations
- Playwright renders HTML captions to PNG overlays (services/playwright/)
- High-contrast caption style: white text, dark semi-transparent background
- Bottom-safe positioning (away from engagement focal area)

## ffmpeg Mux/Finalize Scripts (services/ffmpeg/)
- Create finalization scripts for all three formats
- Mux: video track + audio track + caption burn-in
- Output: MP4 H.264, AAC audio, 1080p, safe volume levels
- Format-specific scripts: format1-finalize.sh, format2-finalize.sh, format3-finalize.sh

## Playwright HTML-to-PNG (services/playwright/)
- Script to render furigana HTML to PNG sequences
- One PNG per caption segment (timed to voice)
- Transparent background for Remotion overlay

## openai-whisper Validation (configured)
- Round-trip validation script:
  1. Render video with captions
  2. Run whisper on audio track
  3. Compare whisper output to source script
  4. Flag if accuracy < 95%
- Validates both Japanese and English tracks

## Shared Script Template
- Create universal script template that all three formats consume
- Fields: vocabulary (JLPT-tagged), cultural_moment (from cultural-moments.yaml),
  engagement_sequence, voice_timing, caption_data
- All three formats read from the same template, only visual layer differs

Commit all to GitHub repo.

• Verify the shared infrastructure is in place by running:

ls services/ffmpeg/
ls services/playwright/

• You should see finalization scripts in services/ffmpeg/ (one per format) and the Playwright HTML-to-PNG pipeline in services/playwright/.

Whisper installation failing?

openai-whisper requires ffmpeg installed on your system. If the install fails, verify ffmpeg is accessible in your PATH. On Windows, install via:

winget install ffmpeg

help me fix openai-whisper installation errors on Windows

All three composition pipelines are built and connected. They share the same JLPT-aligned script template, caption pipeline, and voice timing spec. Only the visual layer changes. Next, you will test-render each format to verify audio sync, cultural fidelity, and engagement pacing.

Validate and Test All Three Video Formats

You have three fully built video pipelines. Each one takes a culturally-contextual script and produces a different visual experience for the same vocabulary content.

Before these pipelines can produce real episodes, you need to prove each one works end-to-end. A 30-second test render for each format confirms audio sync, visual quality, cultural scene integrity, and caption accuracy.

In this step, get ready to:

• Test render Format 1 (Remotion+SVG) with a genkan cultural scene.
• Test render Format 2 (Nano Banana Pro) with culturally-prompted autumn market images.
• Test render Format 3 (InstaDoodle) with a bento box whiteboard scene and dual-voice.

Test render Format 1 (Remotion+SVG)

Format 1 combines Manim kana animations, Inkscape SVG cultural scenes, piper-plus voice, and pentatonic music into a single Remotion composition. The test scene places the mascot in a genkan (Japanese entryway), removing shoes, and repeating "kutsu" three times.

• Create the test output directory by running this command:

mkdir -p services/test-renders

• Navigate into the Remotion SVG project and render the 30-second cultural test scene by running:

cd services/remotion-svg
npx remotion render GenkanTest ../test-renders/format1-test.mp4

What does this command do?

The npx remotion render command renders a composition to a video file. GenkanTest is the composition ID for the 30-second test scene. The output path saves it directly into services/test-renders/.

Remotion bundles your TSX compositions, renders each frame using its built-in browser, encodes with H.264 (the default codec), and muxes audio automatically.

• Once the render completes, play format1-test.mp4 in your media player.
• Verify the following quality gates:

• Audio sync: the word "kutsu" aligns with the shoe-removal animation moment.
• Contrast: text and captions meet WCAG AA (>=7:1 ratio against background).
• No flashing: no rapid brightness changes that could trigger photosensitive responses.
• Volume: voice is clearly audible, music bed is ducked beneath speech.
• Cultural scene: genkan environment renders correctly with shoes, raised floor, and noren.
• Repetition: "kutsu" appears exactly 3 times with appropriate spacing.

Use ffprobe for quick metadata checks

Run ffprobe services/test-renders/format1-test.mp4 in your terminal to quickly verify codec, duration, and resolution without watching the full video. Look for duration around 30 seconds, codec H.264, and 1920x1080 resolution.

Render fails or hangs?

If the render times out, increase the timeout with the --timeout flag. The default is 30000ms per frame. SVG-heavy compositions can be slow on first render while assets load.

If audio is missing, confirm that your piper-plus WAV files exist in the expected path and that your <Audio> components reference the correct relative paths.

Help me debug my Remotion render failure for Format 1

Test render Format 2 (Nano Banana Pro image-stitch)

Format 2 uses AI-generated images from Nano Banana Pro (Gemini 3 Pro Image Preview) stitched together with Ken Burns motion in Remotion. The test generates 3 culturally-specific images depicting a Japanese autumn market scene.

• In Google AI Studio or the Gemini app, generate 3 test images using your culturally-specific prompts from services/image-stitch/. Each prompt should specify the Japanese autumn market context (wooden baskets, maple leaves, child-friendly illustration style).
• Download all 3 images and place them in services/image-stitch/assets/test/.
• Navigate to the image-stitch service and render the 30-second test composition by running:

cd services/image-stitch
npx remotion render AutumnMarketTest ../test-renders/format2-test.mp4

What is this composition doing?

The AutumnMarketTest composition takes your 3 images, applies Ken Burns motion (slow zoom and pan), crossfades between them, and overlays the piper-plus voice track with furigana captions. Each image displays for about 10 seconds, totaling approximately 30 seconds.

• Play format2-test.mp4 and verify the following:

• Cultural authenticity: images depict recognizably Japanese autumn market elements (not generic stock-photo produce).
• Image quality: no artifacts, text rendering is clean, child-friendly illustration style is consistent.
• Transitions: crossfades are smooth with no jarring cuts.
• Audio sync: voice narration aligns with image transitions.
• Captions: furigana text is legible against all 3 image backgrounds.

Why batch your image generation?

Google AI Pro has compute-based usage limits that refresh every 5 hours with a weekly cap. Generate all test images in a single session to avoid hitting the refresh boundary mid-render.

For a full episode (15-20 images), plan one focused generation session rather than spreading it across multiple days.

Images look generic or low quality?

If the images lack Japanese cultural specificity, revisit your prompt templates in services/image-stitch/. Prompts must explicitly specify Japanese context: "Japanese autumn market" not just "fruit market." Include cultural markers like wooden baskets, noren curtains, or maple leaves.

Help me improve my Nano Banana Pro prompts for cultural authenticity

Test render Format 3 (InstaDoodle whiteboard sketch)

Format 3 uses InstaDoodle whiteboard animations composed in Remotion with dual-voice SAPI5 narration (Haruka for Japanese, Zira for English). The test scene draws a bento box being assembled while teaching the word for bento.

• In InstaDoodle Pro, generate the bento box whiteboard scene using your culturally-themed script from services/instadoodle/. Export as MP4.
• Place the exported clip in services/instadoodle/assets/test/.
• Generate the dual-voice SAPI5 audio by running this PowerShell script:

# Generate Japanese voice (Haruka) for bento scene
Add-Type -AssemblyName System.Speech
$synth = New-Object System.Speech.Synthesis.SpeechSynthesizer
$synth.SelectVoice("Microsoft Haruka Desktop")
$synth.SetOutputToWaveFile("services/instadoodle/assets/test/jp-voice.wav")
$synth.Speak("おべんとう。おべんとう。おべんとう。")
$synth.Dispose()

# Generate English voice (Zira) for bento scene
$synth2 = New-Object System.Speech.Synthesis.SpeechSynthesizer
$synth2.SelectVoice("Microsoft Zira Desktop")
$synth2.SetOutputToWaveFile("services/instadoodle/assets/test/en-voice.wav")
$synth2.Speak("Bento box. Bento box. Bento box.")
$synth2.Dispose()

Why dual-voice for Format 3?

The whiteboard format mimics a parent sketching at the kitchen table. Alternating between Japanese (Haruka) and English (Zira) voices reinforces bilingual connection.

The child hears the Japanese word paired with its English equivalent while watching the element being drawn. This multimodal pairing strengthens vocabulary retention.

• Navigate to the instadoodle service and render the 30-second test composition by running:

cd services/instadoodle
npx remotion render BentoTest ../test-renders/format3-test.mp4

• Play format3-test.mp4 and verify the following:

• Reveal pacing: each bento element (rice, vegetables, tamagoyaki) draws one at a time matching the voice timing.
• Cultural element clarity: the bento box is recognizably Japanese (compartmentalized, with chopsticks).
• Dual-voice sync: Japanese and English voices alternate cleanly without overlap.
• Engagement feel: the sketch reveal creates anticipation ("what is being drawn?") before the word is spoken.

Audio out of sync with drawing?

If the voice plays before or after the corresponding sketch element appears, adjust the timing offsets in your Remotion composition. The SSML rate should be 0.85-0.92 with 250-400ms breaks between EN-JP pairs.

Check that your <OffthreadVideo> segments align with the <Audio> start frames in your composition timeline.

Help me fix audio-visual sync in my InstaDoodle Remotion composition

All three formats are rendered. Now run caption validation across all three test renders using openai-whisper. This round-trip test confirms that what the voice says can be accurately transcribed back, proving pronunciation clarity.

• Run Whisper on all three renders to validate caption accuracy by running these commands:

whisper services/test-renders/format1-test.mp4 --language Japanese --model medium --output_dir services/test-renders/
whisper services/test-renders/format2-test.mp4 --language Japanese --model medium --output_dir services/test-renders/
whisper services/test-renders/format3-test.mp4 --language Japanese --model medium --output_dir services/test-renders/

Why the medium model for Japanese?

Whisper's turbo model is optimized for English transcription and is not trained for translation tasks. For non-English audio like Japanese, the multilingual models (medium or large) produce significantly better results.

The medium model requires approximately 5 GB VRAM, which fits comfortably on your 8 GB RTX 2060 Super while providing accurate Japanese transcription.

• Review the generated .txt files in services/test-renders/ and compare each transcription against the original script.
• Confirm >=95% accuracy. If accuracy drops below that threshold, investigate whether the issue is voice synthesis quality or background music interference.
• Log any issues and fix them. Common fixes: reduce music volume, slow down speech rate, or switch to piper-plus for clearer pronunciation.
• Once all three pass >=95% accuracy, commit the test renders and results by running:

git add services/test-renders/
git commit -m "Add test renders and whisper validation for all 3 formats"

What does this commit include?

This commit saves your three test MP4 files (format1-test.mp4, format2-test.mp4, format3-test.mp4) plus the Whisper-generated transcription files. These serve as your validation baseline for the pipeline.

• Confirm the commit succeeded by checking your git log.

All three pipelines are validated. Each format produces watchable, culturally authentic, engagement-ready video with synchronized audio and accurate captions. Next, you will wire these validated pipelines into the Council evaluation and Codex adversarial review system.

Run Council Evaluation, Codex Adversarial Review, and Self-Improvement

Your three video formats are validated with confirmed audio sync, contrast ratios, and Whisper accuracy. The pipeline can produce video, but video quality is only as good as the evaluation framework behind it.

In this step, you will run the full 26-agent council evaluation across all three test renders, deploy Codex as an adversarial reviewer to catch anything Claude missed, and wire up the self-improvement loop so the next video is always better than the last.

In this step, get ready to:

• Execute the council grading rubric across all three test renders with a cultural fidelity dimension.
• Run a Codex adversarial review covering JLPT accuracy, pronunciation, cultural accuracy, and compliance.
• Trigger the self-improvement loop and configure quarterly Firecrawl source checks.

Execute the council grading rubric with cultural fidelity

A grading rubric ensures every video meets the same quality bar before reaching the client. Your rubric covers seven dimensions: the language accuracy you expect from JLPT alignment, the cultural authenticity that makes vocabulary stick, and the engagement science that keeps a toddler watching.

• Switch to Claude Desktop and start a new conversation.
• Paste the following council grading prompt to evaluate all three test renders:

# Council Grading: Evaluate Test Renders

Using the 26-agent council, evaluate format1-test.mp4, format2-test.mp4, and format3-test.mp4 against this rubric:

## Grading Dimensions (score each 1-5)

1. **Voice Script** - JLPT scope accuracy, register appropriateness, clarity of pronunciation
2. **Cultural Fidelity** - Is the cultural context authentic? Would a Japanese parent recognize it? Is it age-appropriate?
3. **Visual** - Engagement design, cognitive load management, age-fit of imagery
4. **Audio** - Pacing, repetition timing, music integration
5. **Composition** - AAP compliance, duration appropriateness, co-viewing suitability
6. **Engagement** - Anticipation pacing, musical mnemonics, multimodal redundancy, 3x repetition present
7. **Technical** - WCAG contrast >=7:1, Whisper round-trip >=95%, safety checklist pass

## Instructions
- Score each dimension per format (3 formats x 7 dimensions = 21 scores)
- Flag any score below 3 with a specific improvement recommendation
- Reference cultural-moments.yaml for Cultural Fidelity validation
- Reference curriculum-ladder.yaml for Voice Script scope validation
- Output results as a structured grading report
- Save results to docs/council-grading-results.md

What do these seven dimensions cover?

Voice Script checks that every word maps to the correct JLPT level and uses natural register. Cultural Fidelity ensures the cultural context would feel authentic to a Japanese parent. Visual measures whether the imagery holds attention without overwhelming a young child.

Audio evaluates pacing and repetition timing. Composition verifies AAP screen-time compliance. Engagement checks for the Blue's Clues repetition model. Technical confirms accessibility and caption accuracy.

• Wait for Claude to produce the grading report across all three formats.
• Review the scores. Any dimension scoring below 3 will feed into the self-improvement loop later in this step.

Why Cultural Fidelity as its own dimension?

Language without culture is hollow. A child hearing "ichi, ni, san" in a void learns numbers. A child hearing them while watching a family count steps to the genkan learns both numbers AND the daily rhythm of a Japanese household. Cultural Fidelity ensures every vocabulary set arrives inside an authentic moment, not as isolated flashcards.

Claude not referencing the YAML files?

Confirm that cultural-moments.yaml and curriculum-ladder.yaml are inside the filesystem MCP's allowed paths. Claude needs MCP file access to read them during evaluation.

If MCP cannot reach the files, paste the relevant YAML sections directly into the prompt as context.

Help me troubleshoot why Claude's council grading can't access my vault YAML files via MCP

Run the Codex adversarial review

Cross-model validation prevents echo-chamber bias. Claude produced the content and evaluated it. Now Codex reviews the same output independently, looking for errors Claude might miss in its own work.

• Open the ChatGPT desktop app on Windows.
• Navigate to Codex in the left sidebar.
• Select your project repository and start a new task with the following review prompt:

# Adversarial Review: Bilingual Video Pipeline Output

Review the following against canonical sources. Flag ANY discrepancy.

## Review Checklist
(a) **JLPT Accuracy** - Every vocabulary item mapped to correct JLPT level per www.jlpt.jp/e/
(b) **Pronunciation** - All romanization and kana match standard Tokyo dialect
(c) **Register per NHK** - Speech patterns match NHK WORLD Easy Japanese beginner register
(d) **Cultural Accuracy** - Cultural references are authentic, not stereotyped or invented
(e) **AAP Compliance** - Episode duration, pacing, and engagement patterns meet AAP 2016+2024 guidance
(f) **Spaced-Repetition Correctness** - curriculum-ladder.yaml progression is pedagogically sound

## Files to Review
- docs/council-grading-results.md (Claude's self-evaluation)
- cultural-moments.yaml
- curriculum-ladder.yaml
- Agent templates in 07-AGENTS/

## Output Format
- For each item (a-f): PASS or FAIL with citation
- Any FAIL includes: what is wrong, what canonical source says, suggested fix
- Flag any disagreement with Claude's council grading scores

Why Codex as the adversarial reviewer?

Codex runs on a different model family from Claude. When Claude generates content and evaluates its own output, it may reproduce the same blind spots in both passes. Codex brings an independent perspective to catch factual errors, pronunciation mistakes, or cultural inaccuracies that Claude might consistently overlook.

Any disagreement between Codex and Claude gets escalated to you (the operator) for final judgment.

• Wait for Codex to complete the review. This typically takes 1-5 minutes depending on repository size.
• If Codex flags any FAIL items, copy the findings back to Claude Desktop.
• Ask Claude to validate each Codex finding. If Claude agrees, apply the fix. If Claude disagrees, make the final call yourself as the operator.
• Log all disagreements and resolutions in a file called docs/codex-review-log.md in your repository.

Codex not seeing your repository files?

Codex requires your GitHub repository to be connected. Confirm the repository is linked in the Codex environment settings. If files are only local, push the latest commit before starting the Codex review.

Help me connect my repository to Codex for the adversarial review

Trigger self-improvement and configure Firecrawl quarterly checks

The self-improvement loop closes the feedback cycle. Lowest-scoring dimensions from the council grading become targeted prompt improvements. Firecrawl keeps your canonical data sources current so the system never drifts from the latest JLPT, NHK, or AAP guidance.

• Return to Claude Desktop and paste the following self-improvement prompt:

# Self-Improvement Loop

Based on the council grading results and Codex review findings:

1. **Identify lowest-scoring areas** across all 3 formats
2. **Generate prompt diffs** for affected agent templates:
   - Show the BEFORE and AFTER for each template section
   - Focus on the specific weakness (e.g., if Cultural Fidelity scored 2/5, update A5's cultural context selection logic)
3. **Version increment** all modified templates (e.g., v1.0 → v1.1)
4. **Update SELF-IMPROVEMENT.md** with:
   - Date of improvement cycle
   - Which agents were updated
   - What scores triggered the update
   - The prompt diffs applied
   - New version numbers
5. **Update cultural-moments.yaml** if Codex flagged any cultural inaccuracies
6. **Finalize DATA-SOURCES.md** with the complete canonical source registry and fact-checking chain

Present all diffs for my approval before applying.

What does the version increment look like?

Each agent template carries a version number in its frontmatter. When the self-improvement loop updates a template, the version increments (v1.0 to v1.1). SELF-IMPROVEMENT.md tracks the full history: which cycle triggered the change, what scores motivated it, and the exact diff applied.

This creates an auditable trail. Six months from now, you can trace why A5's cultural context prompt reads the way it does.

• Review the prompt diffs Claude presents. Approve each change or request modifications.
• Once approved, confirm Claude has updated the affected agent templates and SELF-IMPROVEMENT.md.
• Now configure the quarterly Firecrawl source freshness check by pasting this prompt:

# Firecrawl Quarterly Source Check

Using the Firecrawl MCP server, scrape the following canonical sources and compare against our stored versions:

## Sources to Check
1. JLPT Level Summary: https://www.jlpt.jp/e/about/levelsummary.html
2. JLPT Test Sections: https://www.jlpt.jp/e/guideline/testsections.html
3. NHK WORLD Easy Japanese: https://www3.nhk.or.jp/nhkworld/lesson/en/lessons/
4. Japan Foundation Resources: https://www.jpf.go.jp/e/project/japanese/education/resource/
5. AAP Screen-Time Guidance (latest policy statement page)

## Actions
- Use firecrawl_scrape for each URL
- Compare scraped content against DATA-SOURCES.md stored summaries
- Flag any changes (new JLPT vocabulary lists, updated AAP recommendations, new JF resources)
- Update DATA-SOURCES.md with last-checked date
- Update FIRECRAWL-SCHEDULE.md with:
  - Today's date as first run
  - Next quarterly check dates (3 months, 6 months, 9 months, 12 months)
  - Which sources to check
  - What to do if changes are detected (trigger self-improvement cycle)

Run the first check now.

What does Firecrawl do here?

Firecrawl's firecrawl_scrape tool fetches live content from each canonical source URL. Claude compares the scraped content against what your DATA-SOURCES.md currently records. If JLPT adds new vocabulary to N5 or AAP updates their screen-time guidance, the system catches it and triggers a new self-improvement cycle.

• Confirm that Claude successfully scrapes at least the JLPT and NHK sources. Some sources may require waitFor delays for JavaScript rendering.
• Verify that FIRECRAWL-SCHEDULE.md now contains the quarterly schedule with your first-run date.
• Verify that DATA-SOURCES.md is finalized with the canonical source registry and fact-checking chain.
• Commit all updates to your GitHub repository.

Firecrawl scrape returning empty content?

Some pages (especially JLPT and NHK) use JavaScript rendering. Add waitFor: 5000 to the scrape arguments to give the page time to load before extraction.

If a source blocks scraping entirely, manually check the page and update DATA-SOURCES.md with the current content. Note the manual check date in FIRECRAWL-SCHEDULE.md.

Help me fix Firecrawl scraping issues with Japanese educational sites

Your pipeline now evaluates itself, gets fact-checked by an independent model, improves its weakest points, and keeps its sources current. Next up, you will trigger the full end-to-end pipeline for a real client scenario.

Trigger the Theme-Triggered Client Pipeline

Your 26-agent council is built, graded, and self-improving. Your three video format pipelines are validated. Now it's time to simulate what a real client interaction looks like.

A heritage-Japanese mother in the US says "numbers 1-5" and your system produces a culturally immersive bilingual video. Not flashcards in a void. Numbers taught during a Japanese morning routine, counting steps to the genkan, counting rice bowls at breakfast, counting sakura petals falling.

In this step, get ready to:

• Create the client context files that define who the family is and what their child needs.
• Trigger EP001 ("numbers 1-5") through the full 26-agent council pipeline with Codex review and human gate.
• Verify future-proofing: age-adaptation, spaced repetition, self-improvement, and cultural calendar.

Create the client context

Every theme-triggered run starts with knowing who the child is. The client context files tell your agents the family's background, the child's current developmental stage, and the learning goals.

• In Claude Desktop, instruct Claude to create family-context.yaml in your vault by providing the following client brief:

# family-context.yaml
# Client profile for theme-triggered pipeline

client:
  type: heritage-family
  country: US
  heritage: Japanese

mother:
  language_level: conversational-japanese
  can_teach_structurally: false
  goals:
    - bilingual-development
    - cultural-connection
    - heritage-identity
  notes: >
    Knows conversational Japanese but cannot teach it structurally.
    Wants daughter to grow up bilingual AND culturally connected to Japan.
    Not just words. Understanding. The why behind itadakimasu.

child:
  name_placeholder: "[daughter]"
  age_months: 14
  languages_exposed:
    - english (primary environment)
    - japanese (mother, media)
  cultural_exposure: limited-us-based

delivery:
  trigger_method: theme-keyword
  format_preference: all-three
  co_viewing: required
  parent_guide: required-with-cultural-talking-points

What does this file do?

This YAML file is the entry point for every pipeline run. Your agents read it to understand who they're producing content for.

The goals array tells Agent A5 (Cultural Bridge) to prioritize cultural context in every vocabulary selection. The co_viewing: required flag activates Agent F2 to generate a parent guide with cultural talking points.

• Next, instruct Claude to create target-child-profile.yaml that maps the child to the correct age-band and JLPT level:

# target-child-profile.yaml
# Developmental profile for curriculum scoping

child_id: ep001-target
age_months: 14
age_band: infant-toddler  # 12-24 months

jlpt_level: pre-n5
# Pre-N5: pre-verbal/early-verbal exposure phase
# Focus: sound patterns, single words, cultural routines
# NOT sentence construction or grammar

cell_yaml_applied: true
cell_parameters:
  max_new_vocabulary: 5
  repetition_minimum: 3
  max_duration_seconds: 300  # 5 minutes (AAP compliant)
  pacing: slow
  direct_address: true
  musical_mnemonics: true
  anticipation_pauses: true

engagement_profile:
  attention_span_seconds: 45-60  # per segment
  preferred_modalities:
    - visual (high contrast, single focal)
    - auditory (slow, clear, repetitive)
    - musical (pentatonic, simple melody)
  response_style: call-and-response

cultural_readiness:
  comprehension: pre-verbal-exposure
  target: daily-routines  # itadakimasu, genkan, counting
  avoid: abstract-values  # gambaru/wa too complex at 14mo

What does the age-band calibration do?

Agent A4 (Age-Band Calibrator) reads this profile and applies constraints from cell.yaml for the 12-24 month band. At 14 months, the child is pre-verbal. The system teaches through sound patterns and cultural routines, not grammar.

The cultural_readiness section scopes what kind of cultural moments are appropriate. Daily routines (concrete, visible, repeatable) are perfect. Abstract values like gambaru or wa are deferred to later age bands.

• Confirm both files are saved in your vault by checking that Claude's MCP filesystem response shows the files written successfully.

Claude can't write the files?

Make sure your filesystem MCP server in claude_desktop_config.json includes the vault path in its allowed directories. Claude can only write to paths explicitly listed in the MCP config.

Help me debug MCP filesystem permissions for my Claude Desktop config

Trigger EP001 through the full council pipeline

This is the moment the entire system comes together. You give Claude a theme, and 26 agents produce a culturally immersive bilingual video checked by Codex and gated by you.

• In Claude Desktop, provide the theme trigger prompt. This is what the client would say:

# EP001 Theme Trigger

Theme: "numbers 1-5"
Client: family-context.yaml
Child: target-child-profile.yaml
Output formats: all three
Output directory: services/output/ep001/

## Instructions

1. A5 (Cultural Bridge): Select cultural moment from cultural-moments.yaml for "numbers"
   - Expected: Japanese morning routine (counting steps to genkan, counting rice bowls at breakfast, counting sakura petals)
2. Run full Team A (Curriculum + Pedagogy) pipeline
3. Run Team B (Linguistic Accuracy) validation
4. Run Team C (Visual + Motion) for all three formats
5. Run Team D (Audio + Voice) with piper-plus primary
6. Run Team E (Quality + Safety) checks
7. Run Team F (Family Engagement) - generate co-viewing guide with cultural talking points
8. Council grading with all 7 dimensions
9. Output to services/output/ep001/:
   - ep001-format1.mp4 (Remotion + SVG)
   - ep001-format2.mp4 (Nano Banana Pro image-stitch)
   - ep001-format3.mp4 (InstaDoodle whiteboard)
   - co-viewing-guide-ep001.md

Hold at human gate before final render.

What happens when you trigger?

Agent A5 (Cultural Bridge) reads cultural-moments.yaml and selects "Japanese morning routine" as the cultural moment for numbers. The child doesn't learn ichi-ni-san in isolation. She sees a family counting steps to the genkan, counting rice bowls at breakfast.

Each team runs sequentially: curriculum scoping, linguistic validation, visual composition, audio production, safety checks, and family engagement. The council grades the output across all 7 dimensions including Cultural Fidelity.

• Monitor Claude's progress as it runs through each team. This takes several minutes depending on your session's compute allocation.
• When Claude reaches the human gate, review the council grading scores across all 7 dimensions.
• Verify that Cultural Fidelity scores 4/5 or higher. If any dimension scores below 3/5, instruct Claude to iterate on that dimension before proceeding.

• Open ChatGPT Desktop and send the EP001 script to Codex for adversarial review. Codex checks:

• JLPT accuracy: are all vocabulary items within Pre-N5 scope.
• Pronunciation correctness against standard Tokyo dialect.
• Register validation per NHK standards.
• Cultural accuracy: is this how a Japanese family would actually teach this.
• AAP compliance for the 14-month age band.
• Spaced-repetition correctness in curriculum-ladder.yaml.

• Return Codex's findings to Claude. If Codex flags any issues, instruct Claude to resolve them. If Claude and Codex disagree, you (the operator) make the final call.
• Once all checks pass, approve the human gate. Instruct Claude to render all three formats to services/output/ep001/.

Why a human gate?

The content is for a 14-month-old child. No matter how good the agents are, a human reviews before delivery. This is both a safety requirement (AAP, COPPA) and a quality standard. You are the final check that the cultural context feels authentic and age-appropriate.

• Verify the three output files exist by running:

ls services/output/ep001/

You should see ep001-format1.mp4, ep001-format2.mp4, ep001-format3.mp4, and co-viewing-guide-ep001.md listed.

Renders failing or incomplete?

Format 2 (Nano Banana Pro) depends on Google AI Pro compute limits that refresh every 5 hours. If image generation is throttled, wait for the refresh window and retry the image batch.

For Format 1 and 3, check that Remotion has access to all asset paths (SVGs, audio WAVs, whiteboard clips). Missing assets cause silent render failures.

Help me debug my EP001 render pipeline

Verify future-proofing across age bands, repetition, and self-improvement

A single video is not the goal. The goal is a system that grows with the child from 14 months through adulthood. This substep verifies that the pipeline is ready for years of continuous operation.

• Instruct Claude to test age-adaptation by running the "numbers 1-5" theme against three different child profiles:

# Age-adaptation verification matrix
# Claude tests the same theme across three developmental stages

test_profiles:
  - age_months: 14
    jlpt_level: pre-n5
    expected_output: >
      Sound patterns, single words, slow pacing, call-and-response.
      Cultural moment: morning routine counting (concrete, visible).
      Max 5 words. 3x repetition minimum.

  - age_months: 60  # 5 years old
    jlpt_level: n5
    expected_output: >
      Simple sentences, counting objects in context, interactive prompts.
      Cultural moment: expanded to include market counting, festival games.
      Can introduce ichi-ni-san-shi-go vs hitotsu-futatsu distinction.

  - age_months: 120  # 10 years old
    jlpt_level: n4
    expected_output: >
      Number + counter combinations (人, 個, 本, 匹).
      Cultural moment: train platform numbers, floor numbers in department stores.
      Reading practice with simple kanji (一二三四五).

Why test three age bands for the same theme?

"Numbers" means completely different things at 14 months vs 10 years. At 14 months it's sound exposure. At 5 years it's basic counting in context. At 10 years it's counter suffixes and kanji. The same theme triggers age-appropriate content without the mother needing to know JLPT scoping.

• Verify that Claude produces distinct curriculum plans for each age band. The 14-month plan should have max 5 words. The 5-year plan should introduce simple sentences. The 10-year plan should include counter suffixes.
• Instruct Claude to verify spaced repetition in curriculum-ladder.yaml. After EP001, the numbers 1-5 vocabulary should be logged with a next-review date.
• Confirm that the self-improvement loop triggered from EP001 results. Claude should have identified the lowest-scoring dimension from the council grading and proposed a prompt improvement.
• Check SELF-IMPROVEMENT.md for the EP001 improvement log entry with a version increment on the affected agent template.

• Finally, instruct Claude to generate the cultural calendar. Based on the current season and the family context, the system should suggest the next theme:

# Cultural calendar output (generated by system)
# Based on: current season + child age + completed episodes

current_season: # system reads current date
completed_themes:
  - numbers (EP001)

suggested_next:
  primary: # seasonal suggestion based on current month
    # Spring: sakura/hanami vocabulary
    # Summer: matsuri/fireworks vocabulary
    # Autumn: fruits at harvest market
    # Winter: oshogatsu/new year vocabulary
  rationale: >
    Seasonal themes connect the child's daily environment
    to Japanese cultural calendar. The mother can reinforce
    by pointing out seasonal elements in their own neighborhood.
  alternative:
    theme: daily-greetings  # ohayou, itadakimasu, oyasumi
    rationale: >
      High-frequency daily routines reinforce fastest.
      Mother can practice these every single day.

What makes the cultural calendar powerful?

The system doesn't just produce videos on demand. It proactively suggests what the child should learn next based on the Japanese cultural calendar. If it's October, the system suggests autumn vocabulary taught at a harvest market. If it's December, it suggests oshogatsu preparation words.

This mirrors how Japanese kindergartens work. Curriculum follows seasons, not arbitrary topic order. The child grows up with the same seasonal awareness that children in Japan experience naturally.

• Instruct Claude to commit all EP001 outputs, client context files, calendar, and SELF-IMPROVEMENT.md updates to the GitHub repository.
• Verify the commit includes: family-context.yaml, target-child-profile.yaml, the three EP001 MP4s, the co-viewing guide, and the cultural calendar.

Self-improvement not triggering?

Check that your council grading completed with numerical scores. The self-improvement loop reads the lowest-scoring dimension and targets that agent's prompt template. If grading returned qualitative feedback instead of numbers, instruct Claude to re-grade with the 1-5 numeric rubric.

Help me debug the self-improvement loop for EP001

Your pipeline just did something remarkable. A mother said "numbers" and your system delivered a video where her daughter doesn't just hear ichi-ni-san. She sees a Japanese family counting steps to the genkan, counting rice bowls at breakfast. The co-viewing guide tells mom to count their own steps together tomorrow. The system logged what it learned and will be better next time. And the cultural calendar already knows what to suggest next season.

Secret mission

Full EP001 + Cultural Heritage Verification

Your pipeline produced three EP001 videos. But production is not proof. Can you verify that every frame, every word, every cultural moment meets the quality bar? Run the full verification gauntlet: Whisper round-trip, council grading, Codex adversarial review, cultural authenticity triple-check, engagement science audit, age-adaptation scaling, and spaced repetition confirmation. Prove that your toddler doesn't just hear ichi-ni-san. She sees a family counting steps to the genkan.

Clean Up Your Resources

Clean Up Your Resources

This project runs entirely on your local machine and uses subscriptions you already own (Claude Max, ChatGPT Plus, Google AI Pro, InstaDoodle Pro). The project files on disk do not generate ongoing costs.

Decide whether to keep your resources running, pause them to come back later, or delete them entirely.

Resources you used:

• Local project directory (Obsidian vault, service directories, video outputs, agent templates).
• MCP server entries added to claude_desktop_config.json.
• Python packages installed via pip (piper-plus, PyKakasi, SudachiPy, fugashi, openai-whisper, manim, playwright).
• GitHub remote repository.

Keep everything running

No action needed. Choose this if you plan to continue producing episodes or refining the pipeline.

• Your project files remain on disk and ready for the next theme trigger.
• The Firecrawl quarterly schedule stays active whenever Claude Desktop is running.
• Your existing subscriptions (Claude Max 20x, ChatGPT Plus, Google AI Pro, InstaDoodle Pro) continue billing independently of these files.

Pause - I'll come back to this later

Free up background resources while keeping all files intact for later.

• Open claude_desktop_config.json at %APPDATA%\Claude\claude_desktop_config.json and comment out or remove the Firecrawl MCP server entry. This stops quarterly background checks.
• Close Obsidian to release the vault lock and free memory.
• Your project folder, GitHub repo, and installed packages remain ready. Restart Obsidian and re-add the Firecrawl entry when you return.

Delete - I don't want to use this again

Remove all project resources from your machine and start fresh.

• Delete the local project directory by opening PowerShell and running the command below. Replace the path with your actual project folder location on the Desktop:
• Uninstall the Python packages this project added by running:
• Revert your MCP configuration. Open %APPDATA%\Claude\claude_desktop_config.json in a text editor. Remove the filesystem, git, sqlite, and Firecrawl server entries you added in Step 2. Save the file and restart Claude Desktop.
• Delete the GitHub remote repository. On GitHub, navigate to your repository page. Click Settings. Scroll down to the Danger Zone section. Click Delete this repository. Follow the confirmation prompts and type the repository name to confirm.

That's a Wrap!

That's a Wrap!

You built a self-improving bilingual education system that doesn't just teach Japanese words. It immerses a heritage child in the culture their family came from.

You've learned how to:

• Build a theme-triggered pipeline where a mother says a word and 26 parallel agents produce a JLPT-aligned bilingual video with language taught inside authentic Japanese cultural moments.
• Wire cross-model adversarial validation where Codex independently fact-checks Claude's Japanese accuracy, cultural claims, and safety compliance against canonical sources.
• Build a self-improving agentic system with spaced repetition, age-adaptive curriculum scaling from 14 months through N1, quarterly source freshness via Firecrawl, and version-tracked prompt updates that make each video better than the last.
• Produced EP001 across all three visual formats. A toddler learns counting inside a Japanese morning routine. The co-viewing guide says "Count your steps together tomorrow. Ichi, ni, san."

The system is ready. A mother says "fruits" and her daughter sees ringo at an autumn market, hears it three times in a gentle cultural scene, and closes with a musical mnemonic. The guide tells mom about 食欲の秋 and suggests visiting a farmers market together. Next video will be better. The system grows with her daughter, and her daughter grows up knowing not just the language, but the world it comes from.

Ready to quiz yourself?