CLAUDE.md

1# CLAUDE.md — C4Sight Video Engine
2 
3This file is your complete briefing. Read it fully before touching any code.
4 
5---
6 
7## What This Project Is
8 
9C4Sight is an animated educational YouTube series explaining AI clearly, practically, and without hype. It is produced by C4 Studios (Perth, WA). The production pipeline uses **Remotion** (React-based programmatic video). This repo is the video engine that renders the episodes.
10 
11**The show's editorial POV:** AI is more useful than the doomers say, less magical than the hypers say, and almost everyone outside the industry is getting both wrong.
12 
13**Episode 1 title:** "Is AI Actually Magic?"
14**Central question:** Is AI actually magic, or are we just bad at understanding it?
15 
16---
17 
18## Your Role
19 
20You are the primary engineering agent for this repo. You operate with full creative and technical authority within the constraints of this file.
21 
22**Before writing any code in a session:**
231. Run `find . -type f \( -name "*.tsx" -o -name "*.ts" \) | grep -v node_modules | grep -v .next | sort` to see the current file tree.
242. Read all files in `src/design-system/`, `src/layout/`, `src/data/`, and `src/video/`.
253. Read `src/Root.tsx` to see what compositions are registered.
264. Check `reference/` for Figma Make source assets and character code.
275. Report the current state before making changes.
28 
29**Operating mode:** Audit → plan → confirm with user → execute. Never make sweeping changes without a plan review.
30 
31---
32 
33## The Creative Source of Truth (Show Bible v1.0)
34 
35### Palette — Six Colours. Locked. No Others.
36 
37| Token | Hex | Use |
38|---|---|---|
39| `slate` | `#1A1F1C` | Blackboard backgrounds, dark mode |
40| `chalk` | `#F4EDE0` | Chalk text, primary type on dark |
41| `paper` | `#EFE7D6` | Main world backgrounds |
42| `verifyRed` | `#D7382C` | Verify stamp, warnings, emphasis |
43| `wizardLavender` | `#B9A8C7` | Wizard mascot body |
44| `ink` | `#221F1F` | Line art, type on light backgrounds |
45 
46**Hard rule:** If a colour outside these six exists in any component, flag it and remove it. Known violations to fix: `#E8C66B` (yellow/amber) and `#A5B89A` (green) appear in some Figma Make styleframe files — remove them. Yellow accent underlines on the blackboard become `chalk` at 65% opacity. Traffic light dots in UI mode: red stays `verifyRed`, yellow becomes `chalk`, green becomes `ink` at 35% opacity.
47 
48### Typography
49 
50```ts
51titleFamily:     '"Fraunces", "Playfair Display", Georgia, serif'
52bodyFamily:      '"DM Sans", "Plus Jakarta Sans", Inter, system-ui, sans-serif'
53captionFamily:   '"DM Sans", Inter, system-ui, sans-serif'
54chalkHandFamily: '"Caveat", "Patrick Hand", cursive'
55```
56 
57**Critical:** All text rendered ON a blackboard uses `chalkHandFamily` (Caveat/Patrick Hand). Recoleta/Tiempos are show typography, not chalk typography. Any blackboard label in serif display font is wrong.
58 
59Install `@remotion/google-fonts` if not present. Load Fraunces, DM Sans, and Caveat in `src/Root.tsx`.
60 
61### The Four Visual Modes
62 
63Every scene in every episode belongs to exactly one mode. Modes are defined in `src/layout/c4sightSceneGrammar.ts`.
64 
65| Mode | Background | Used For |
66|---|---|---|
67| `mainWorld` | paper (#EFE7D6), warm | Hooks, humour, story, host home base |
68| `blackboard` | slate (#1A1F1C) | Teaching, definitions, diagrams |
69| `interfaceTool` | dark (#252B27) | AI tools, agents, prompts, workflows |
70| `humanJudgement` | paper, more saturated | Ethics, jobs, real-world stakes |
71 
72Mode cuts between scenes are **hard cuts**. The eraser wipe transition is reserved exclusively for exiting the blackboard. Do not dilute it.
73 
74### The Mascot — Tiny Alien Wizard
75 
76He represents magical thinking about AI. Lovable, slightly desperate, always wrong.
77 
78- Body: wizard lavender (#B9A8C7), slightly translucent
79- Hat: slate, three almost-right stars (triangle, wonky pentagon, uneven 5-point)
80- Robe: too long, drags, worn cuffs
81- Eyes: large and tired. Big pupils, small irises.
82- Wand: chalk wand stolen from the host's blackboard
83- **He never speaks.** No speech bubbles. No text attributed to him. Gesture and expression only.
84 
85The wizard SVG component lives in `reference/c4sight_figma_make_source_pack/src/app/components/Wizard.tsx`. It is production-ready pure SVG React. If not already ported to `src/design-system/characters/WizardSVG.tsx`, do this before building any composition.
86 
87### The Host
88 
89Adult, late 20s–mid 30s. Henley or rolled-sleeve button-down, work trousers. Wire-frame glasses optional. Default expression: dry and unimpressed. Always has chalk or a notebook.
90 
91**Expressions:** dry (default), raised-brow, smile (genuine), exasperated, curious.
92**Key poses:** gesture, two-tap-ready (chalk raised before the board taps), brushing-dust (exit ritual).
93 
94Two variants: A (dark hair, oatmeal henley) and B (auburn, slate-blue button-down). The host SVG lives in `reference/c4sight_figma_make_source_pack/src/app/components/Host.tsx`.
95 
96### The Blackboard Ritual
97 
98This is the show's signature device. It must be built with the correct beat structure:
99 
1001. Host says: *"Let's take it to the blackboard."*
1012. Host walks toward board, rolls sleeves.
1023. Host picks up chalk. **Two taps against the board.** This is the audio fingerprint — non-negotiable.
1034. Teaching segment proceeds.
1045. Exit: host puts chalk down, brushes dust off hands, eraser wipe back to main world.
105 
106The two-tap moment uses `timing.ritual` (60 frames) from the token system. Build a `BlackboardRitual` sequence component that handles this beat cleanly and can be reused across episodes.
107 
108### Recurring Devices
109 
110- **Verify Stamp** — red rubber stamp, chunky mechanical thunk. Slams down on confident AI answers. Build as a reusable `VerifyStamp` component.
111- **Wizard walk-off** — wizard from behind, robe dragging, dust puffs. The `WizardFromBehind` SVG exists in the Figma Make source. Port it.
112- **Chalk cards** — small slate boxes with chalk text, slightly askew. Used for "wizard takes credit" floating claims.
113 
114---
115 
116## Current Build Priorities
117 
118Execute in this order. Do not skip ahead.
119 
120### Priority 1 — Design system alignment
121- Ensure `src/design-system/c4sightTokens.ts` has the correct six-colour palette and correct typography (see above).
122- Port `Wizard.tsx` from `reference/` to `src/design-system/characters/WizardSVG.tsx` if not done.
123- Port `Host.tsx` from `reference/` to `src/design-system/characters/HostSVG.tsx` if not done.
124- Update `src/design-system/characters/Mascot.tsx` to use `WizardSVG` by default.
125- Remove all palette violations from any existing files.
126 
127### Priority 2 — Channel Manifesto (60 seconds)
128File: `src/video/C4SightChannelManifesto.tsx`
129Registered in Root.tsx as `'ChannelManifesto'`, 1920×1080, 30fps, 1800 frames.
130 
131Five beats:
1321. Title (0–300f): "C4Sight" wordmark on paper. Wizard peeks in at 6s.
1332. Host intro (300–750f): host + the show's POV in display text.
1343. Wizard debunk (750–1050f): wizard takes credit → "NO." → wizard walks off → "Well… sort of."
1354. Four modes preview (1050–1500f): 3–4 second cut to each mode.
1365. Close (1500–1800f): "AI made clear." with wizard sitting on the wordmark.
137 
138This ships before Episode 1. It proves the pipeline.
139 
140### Priority 3 — Episode 1 Full Composition
141File: `src/video/C4SightEpisode01.tsx`
142Registered as `'Episode01'`, 1920×1080, 30fps, 13500 frames (7.5 min).
143 
144Ten main sequences (from styleframes in `reference/` or repo):
1451. "Is AI magic?" — paper bg, display text, wizard peeks
1462. Wizard takes credit — chalk cards orbiting wizard
1473. "NO." — type-driven, red period, wizard hat drops
1484. Wizard walk-off — behind view, dust, host watches
1495. "Well… sort of." — host thoughtful, wizard peeks back
1506. Blackboard ritual — host walks to board, two taps
1517. Input → Model → Output — blackboard diagram builds progressively
1528. Useful and wrong — interface mode, Verify Red highlight
1539. Verify Stamp — stamp coming down on confident AI answer
15410. "AI made clear." — close, wizard on wordmark
155 
156Build sequences 1–5 first. Render. Then 6–10.
157 
158### Priority 4 — Reusable component library
159After the above work, extract recurring elements into reusable components:
160- `VerifyStamp.tsx` — animated stamp, configurable text
161- `ChalkCard.tsx` — slate box, chalk text, slight rotation prop
162- `BlackboardRitual.tsx` — the full two-tap sequence as a Sequence component
163- `ChalkDiagram.tsx` — arrow-connected box diagram (Input→Model→Output pattern)
164 
165---
166 
167## Build Commands
168 
169```bash
170npm run dev              # Remotion preview (hot reload)
171npx remotion preview     # Alternative preview
172npx remotion render ChannelManifesto --output out/manifesto.mp4
173npx remotion render Episode01 --output out/episode01.mp4
174npm run build            # TypeScript check
175```
176 
177Always run `npm run build` before declaring a task complete. No TypeScript errors.
178 
179---
180 
181## Hard Rules
182 
1831. **Palette is law.** Six colours. No others. Audit with: `grep -r "#" src/ | grep -v "node_modules" | grep -v ".git"` and check for any hex not in the six.
1842. **No new npm dependencies** without asking first. Remotion + React + TypeScript is the stack.
1853. **Read before writing.** Always audit the existing file before editing it.
1864. **No hardcoded colours in components.** All colours from `c4sightTokens.colors`.
1875. **No hardcoded frame counts in components.** All timing from `c4sightTokens.timing`.
1886. **The blackboard two-tap ritual is non-negotiable.** Every blackboard entry must include it.
1897. **The wizard never speaks.** No text attributed to him anywhere.
1908. **Chalk text on blackboards uses Caveat.** Never Recoleta or any serif on slate backgrounds.
1919. **The eraser wipe is reserved for exiting the blackboard.** Not used for any other transition.
19210. **Preview renders before marking tasks done.** `npx remotion preview` must open cleanly.
193 
194---
195 
196## Key File Locations
197 
198```
199src/design-system/c4sightTokens.ts        # Design tokens (palette, type, timing, layout)
200src/design-system/characters/Mascot.tsx   # Wizard component (update to use WizardSVG)
201src/layout/c4sightSceneGrammar.ts         # Scene zones, archetypes, visual mode types
202src/data/brand.ts                         # Show name, tagline, meta
203src/Root.tsx                              # Remotion composition registry
204 
205reference/c4sight_figma_make_source_pack/ # Figma Make outputs
206  src/app/components/Wizard.tsx           # ← port this to WizardSVG.tsx
207  src/app/components/Host.tsx             # ← port this to HostSVG.tsx
208  src/app/components/CharacterSheet.tsx   # Reference only
209  src/app/components/HostSheet.tsx        # Reference only
210```
211 
212---
213 
214## What Not to Touch Without Asking
215 
216- `reference/` — read-only source material, do not modify
217- Any existing video file that is rendering correctly — don't refactor working code
218- `remotion.config.ts` — don't modify without a clear reason
219 
220---
221 
222## Session Start Checklist
223 
224Every Claude Code session begins with:
225 
226- [ ] Read this file fully
227- [ ] Run the find command to see current file tree
228- [ ] Read all files in `src/design-system/`
229- [ ] Read `src/Root.tsx`
230- [ ] Report what's complete, what's broken, what's missing
231- [ ] Propose a plan for this session
232- [ ] Wait for confirmation before executing
233 
234---
235 
236*Show Bible v1.0 · C4 Studios · Perth, WA*
237*This file is maintained by the creative director. Changes to creative direction come through here, not through code comments.*
238