fix: align CI node version to .nvmrc (22), remove redundant gotcha

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.agents/skills/remotion-best-practices/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: remotion-best-practices
+description: Best practices for Remotion - Video creation in React
+metadata:
+  tags: remotion, video, react, animation, composition
+---
+
+## When to use
+
+Use this skills whenever you are dealing with Remotion code to obtain the domain-specific knowledge.
+
+## Captions
+
+When dealing with captions or subtitles, load the [./rules/subtitles.md](./rules/subtitles.md) file for more information.
+
+## Using FFmpeg
+
+For some video operations, such as trimming videos or detecting silence, FFmpeg should be used. Load the [./rules/ffmpeg.md](./rules/ffmpeg.md) file for more information.
+
+## Audio visualization
+
+When needing to visualize audio (spectrum bars, waveforms, bass-reactive effects), load the [./rules/audio-visualization.md](./rules/audio-visualization.md) file for more information.
+
+## Sound effects
+
+When needing to use sound effects, load the [./rules/sound-effects.md](./rules/sound-effects.md) file for more information.
+
+## How to use
+
+Read individual rule files for detailed explanations and code examples:
+
+- [rules/3d.md](rules/3d.md) - 3D content in Remotion using Three.js and React Three Fiber
+- [rules/animations.md](rules/animations.md) - Fundamental animation skills for Remotion
+- [rules/assets.md](rules/assets.md) - Importing images, videos, audio, and fonts into Remotion
+- [rules/audio.md](rules/audio.md) - Using audio and sound in Remotion - importing, trimming, volume, speed, pitch
+- [rules/calculate-metadata.md](rules/calculate-metadata.md) - Dynamically set composition duration, dimensions, and props
+- [rules/can-decode.md](rules/can-decode.md) - Check if a video can be decoded by the browser using Mediabunny
+- [rules/charts.md](rules/charts.md) - Chart and data visualization patterns for Remotion (bar, pie, line, stock charts)
+- [rules/compositions.md](rules/compositions.md) - Defining compositions, stills, folders, default props and dynamic metadata
+- [rules/extract-frames.md](rules/extract-frames.md) - Extract frames from videos at specific timestamps using Mediabunny
+- [rules/fonts.md](rules/fonts.md) - Loading Google Fonts and local fonts in Remotion
+- [rules/get-audio-duration.md](rules/get-audio-duration.md) - Getting the duration of an audio file in seconds with Mediabunny
+- [rules/get-video-dimensions.md](rules/get-video-dimensions.md) - Getting the width and height of a video file with Mediabunny
+- [rules/get-video-duration.md](rules/get-video-duration.md) - Getting the duration of a video file in seconds with Mediabunny
+- [rules/gifs.md](rules/gifs.md) - Displaying GIFs synchronized with Remotion's timeline
+- [rules/images.md](rules/images.md) - Embedding images in Remotion using the Img component
+- [rules/light-leaks.md](rules/light-leaks.md) - Light leak overlay effects using @remotion/light-leaks
+- [rules/lottie.md](rules/lottie.md) - Embedding Lottie animations in Remotion
+- [rules/measuring-dom-nodes.md](rules/measuring-dom-nodes.md) - Measuring DOM element dimensions in Remotion
+- [rules/measuring-text.md](rules/measuring-text.md) - Measuring text dimensions, fitting text to containers, and checking overflow
+- [rules/sequencing.md](rules/sequencing.md) - Sequencing patterns for Remotion - delay, trim, limit duration of items
+- [rules/tailwind.md](rules/tailwind.md) - Using TailwindCSS in Remotion
+- [rules/text-animations.md](rules/text-animations.md) - Typography and text animation patterns for Remotion
+- [rules/timing.md](rules/timing.md) - Interpolation curves in Remotion - linear, easing, spring animations
+- [rules/transitions.md](rules/transitions.md) - Scene transition patterns for Remotion
+- [rules/transparent-videos.md](rules/transparent-videos.md) - Rendering out a video with transparency
+- [rules/trimming.md](rules/trimming.md) - Trimming patterns for Remotion - cut the beginning or end of animations
+- [rules/videos.md](rules/videos.md) - Embedding videos in Remotion - trimming, volume, speed, looping, pitch
+- [rules/parameters.md](rules/parameters.md) - Make a video parametrizable by adding a Zod schema
+- [rules/maps.md](rules/maps.md) - Add a map using Mapbox and animate it
+- [rules/voiceover.md](rules/voiceover.md) - Adding AI-generated voiceover to Remotion compositions using ElevenLabs TTS

.agents/skills/remotion-best-practices/rules/3d.md

@@ -0,0 +1,86 @@
+---
+name: 3d
+description: 3D content in Remotion using Three.js and React Three Fiber.
+metadata:
+  tags: 3d, three, threejs
+---
+
+# Using Three.js and React Three Fiber in Remotion
+
+Follow React Three Fiber and Three.js best practices.  
+Only the following Remotion-specific rules need to be followed:
+
+## Prerequisites
+
+First, the `@remotion/three` package needs to be installed.  
+If it is not, use the following command:
+
+```bash
+npx remotion add @remotion/three # If project uses npm
+bunx remotion add @remotion/three # If project uses bun
+yarn remotion add @remotion/three # If project uses yarn
+pnpm exec remotion add @remotion/three # If project uses pnpm
+```
+
+## Using ThreeCanvas
+
+You MUST wrap 3D content in `<ThreeCanvas>` and include proper lighting.  
+`<ThreeCanvas>` MUST have a `width` and `height` prop.
+
+```tsx
+import { ThreeCanvas } from "@remotion/three";
+import { useVideoConfig } from "remotion";
+
+const { width, height } = useVideoConfig();
+
+<ThreeCanvas width={width} height={height}>
+  <ambientLight intensity={0.4} />
+  <directionalLight position={[5, 5, 5]} intensity={0.8} />
+  <mesh>
+    <sphereGeometry args={[1, 32, 32]} />
+    <meshStandardMaterial color="red" />
+  </mesh>
+</ThreeCanvas>;
+```
+
+## No animations not driven by `useCurrentFrame()`
+
+Shaders, models etc MUST NOT animate by themselves.  
+No animations are allowed unless they are driven by `useCurrentFrame()`.  
+Otherwise, it will cause flickering during rendering.
+
+Using `useFrame()` from `@react-three/fiber` is forbidden.
+
+## Animate using `useCurrentFrame()`
+
+Use `useCurrentFrame()` to perform animations.
+
+```tsx
+const frame = useCurrentFrame();
+const rotationY = frame * 0.02;
+
+<mesh rotation={[0, rotationY, 0]}>
+  <boxGeometry args={[2, 2, 2]} />
+  <meshStandardMaterial color="#4a9eff" />
+</mesh>;
+```
+
+## Using `<Sequence>` inside `<ThreeCanvas>`
+
+The `layout` prop of any `<Sequence>` inside a `<ThreeCanvas>` must be set to `none`.
+
+```tsx
+import { Sequence } from "remotion";
+import { ThreeCanvas } from "@remotion/three";
+
+const { width, height } = useVideoConfig();
+
+<ThreeCanvas width={width} height={height}>
+  <Sequence layout="none">
+    <mesh>
+      <boxGeometry args={[2, 2, 2]} />
+      <meshStandardMaterial color="#4a9eff" />
+    </mesh>
+  </Sequence>
+</ThreeCanvas>;
+```

.agents/skills/remotion-best-practices/rules/animations.md

@@ -0,0 +1,27 @@
+---
+name: animations
+description: Fundamental animation skills for Remotion
+metadata:
+  tags: animations, transitions, frames, useCurrentFrame
+---
+
+All animations MUST be driven by the `useCurrentFrame()` hook.  
+Write animations in seconds and multiply them by the `fps` value from `useVideoConfig()`.
+
+```tsx
+import { useCurrentFrame } from "remotion";
+
+export const FadeIn = () => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+
+  const opacity = interpolate(frame, [0, 2 * fps], [0, 1], {
+    extrapolateRight: "clamp",
+  });
+
+  return <div style={{ opacity }}>Hello World!</div>;
+};
+```
+
+CSS transitions or animations are FORBIDDEN - they will not render correctly.  
+Tailwind animation class names are FORBIDDEN - they will not render correctly.

.agents/skills/remotion-best-practices/rules/assets.md

@@ -0,0 +1,78 @@
+---
+name: assets
+description: Importing images, videos, audio, and fonts into Remotion
+metadata:
+  tags: assets, staticFile, images, fonts, public
+---
+
+# Importing assets in Remotion
+
+## The public folder
+
+Place assets in the `public/` folder at your project root.
+
+## Using staticFile()
+
+You MUST use `staticFile()` to reference files from the `public/` folder:
+
+```tsx
+import { Img, staticFile } from "remotion";
+
+export const MyComposition = () => {
+  return <Img src={staticFile("logo.png")} />;
+};
+```
+
+The function returns an encoded URL that works correctly when deploying to subdirectories.
+
+## Using with components
+
+**Images:**
+
+```tsx
+import { Img, staticFile } from "remotion";
+
+<Img src={staticFile("photo.png")} />;
+```
+
+**Videos:**
+
+```tsx
+import { Video } from "@remotion/media";
+import { staticFile } from "remotion";
+
+<Video src={staticFile("clip.mp4")} />;
+```
+
+**Audio:**
+
+```tsx
+import { Audio } from "@remotion/media";
+import { staticFile } from "remotion";
+
+<Audio src={staticFile("music.mp3")} />;
+```
+
+**Fonts:**
+
+```tsx
+import { staticFile } from "remotion";
+
+const fontFamily = new FontFace("MyFont", `url(${staticFile("font.woff2")})`);
+await fontFamily.load();
+document.fonts.add(fontFamily);
+```
+
+## Remote URLs
+
+Remote URLs can be used directly without `staticFile()`:
+
+```tsx
+<Img src="https://example.com/image.png" />
+<Video src="https://remotion.media/video.mp4" />
+```
+
+## Important notes
+
+- Remotion components (`<Img>`, `<Video>`, `<Audio>`) ensure assets are fully loaded before rendering
+- Special characters in filenames (`#`, `?`, `&`) are automatically encoded

.agents/skills/remotion-best-practices/rules/assets/charts-bar-chart.tsx

@@ -0,0 +1,173 @@
+import {loadFont} from '@remotion/google-fonts/Inter';
+import {AbsoluteFill, spring, useCurrentFrame, useVideoConfig} from 'remotion';
+
+const {fontFamily} = loadFont();
+
+const COLOR_BAR = '#D4AF37';
+const COLOR_TEXT = '#ffffff';
+const COLOR_MUTED = '#888888';
+const COLOR_BG = '#0a0a0a';
+const COLOR_AXIS = '#333333';
+
+// Ideal composition size: 1280x720
+
+const Title: React.FC<{children: React.ReactNode}> = ({children}) => (
+	<div style={{textAlign: 'center', marginBottom: 40}}>
+		<div style={{color: COLOR_TEXT, fontSize: 48, fontWeight: 600}}>
+			{children}
+		</div>
+	</div>
+);
+
+const YAxis: React.FC<{steps: number[]; height: number}> = ({
+	steps,
+	height,
+}) => (
+	<div
+		style={{
+			display: 'flex',
+			flexDirection: 'column',
+			justifyContent: 'space-between',
+			height,
+			paddingRight: 16,
+		}}
+	>
+		{steps
+			.slice()
+			.reverse()
+			.map((step) => (
+				<div
+					key={step}
+					style={{
+						color: COLOR_MUTED,
+						fontSize: 20,
+						textAlign: 'right',
+					}}
+				>
+					{step.toLocaleString()}
+				</div>
+			))}
+	</div>
+);
+
+const Bar: React.FC<{
+	height: number;
+	progress: number;
+}> = ({height, progress}) => (
+	<div
+		style={{
+			flex: 1,
+			display: 'flex',
+			flexDirection: 'column',
+			justifyContent: 'flex-end',
+		}}
+	>
+		<div
+			style={{
+				width: '100%',
+				height,
+				backgroundColor: COLOR_BAR,
+				borderRadius: '8px 8px 0 0',
+				opacity: progress,
+			}}
+		/>
+	</div>
+);
+
+const XAxis: React.FC<{
+	children: React.ReactNode;
+	labels: string[];
+	height: number;
+}> = ({children, labels, height}) => (
+	<div style={{flex: 1, display: 'flex', flexDirection: 'column'}}>
+		<div
+			style={{
+				display: 'flex',
+				alignItems: 'flex-end',
+				gap: 16,
+				height,
+				borderLeft: `2px solid ${COLOR_AXIS}`,
+				borderBottom: `2px solid ${COLOR_AXIS}`,
+				paddingLeft: 16,
+			}}
+		>
+			{children}
+		</div>
+		<div
+			style={{
+				display: 'flex',
+				gap: 16,
+				paddingLeft: 16,
+				marginTop: 12,
+			}}
+		>
+			{labels.map((label) => (
+				<div
+					key={label}
+					style={{
+						flex: 1,
+						textAlign: 'center',
+						color: COLOR_MUTED,
+						fontSize: 20,
+					}}
+				>
+					{label}
+				</div>
+			))}
+		</div>
+	</div>
+);
+
+export const MyAnimation = () => {
+	const frame = useCurrentFrame();
+	const {fps, height} = useVideoConfig();
+
+	const data = [
+		{month: 'Jan', price: 2039},
+		{month: 'Mar', price: 2160},
+		{month: 'May', price: 2327},
+		{month: 'Jul', price: 2426},
+		{month: 'Sep', price: 2634},
+		{month: 'Nov', price: 2672},
+	];
+
+	const minPrice = 2000;
+	const maxPrice = 2800;
+	const priceRange = maxPrice - minPrice;
+	const chartHeight = height - 280;
+	const yAxisSteps = [2000, 2400, 2800];
+
+	return (
+		<AbsoluteFill
+			style={{
+				backgroundColor: COLOR_BG,
+				padding: 60,
+				display: 'flex',
+				flexDirection: 'column',
+				fontFamily,
+			}}
+		>
+			<Title>Gold Price 2024</Title>
+
+			<div style={{display: 'flex', flex: 1}}>
+				<YAxis steps={yAxisSteps} height={chartHeight} />
+				<XAxis height={chartHeight} labels={data.map((d) => d.month)}>
+					{data.map((item, i) => {
+						const progress = spring({
+							frame: frame - i * 5 - 10,
+							fps,
+							config: {damping: 18, stiffness: 80},
+						});
+
+						const barHeight =
+							((item.price - minPrice) / priceRange) * chartHeight * progress;
+
+						return (
+							<Bar key={item.month} height={barHeight} progress={progress} />
+						);
+					})}
+				</XAxis>
+			</div>
+		</AbsoluteFill>
+	);
+};

.agents/skills/remotion-best-practices/rules/assets/text-animations-typewriter.tsx

@@ -0,0 +1,100 @@
+import {
+	AbsoluteFill,
+	interpolate,
+	useCurrentFrame,
+	useVideoConfig,
+} from 'remotion';
+
+const COLOR_BG = '#ffffff';
+const COLOR_TEXT = '#000000';
+const FULL_TEXT = 'From prompt to motion graphics. This is Remotion.';
+const PAUSE_AFTER = 'From prompt to motion graphics.';
+const FONT_SIZE = 72;
+const FONT_WEIGHT = 700;
+const CHAR_FRAMES = 2;
+const CURSOR_BLINK_FRAMES = 16;
+const PAUSE_SECONDS = 1;
+
+// Ideal composition size: 1280x720
+
+const getTypedText = ({
+	frame,
+	fullText,
+	pauseAfter,
+	charFrames,
+	pauseFrames,
+}: {
+	frame: number;
+	fullText: string;
+	pauseAfter: string;
+	charFrames: number;
+	pauseFrames: number;
+}): string => {
+	const pauseIndex = fullText.indexOf(pauseAfter);
+	const preLen =
+		pauseIndex >= 0 ? pauseIndex + pauseAfter.length : fullText.length;
+
+	let typedChars = 0;
+	if (frame < preLen * charFrames) {
+		typedChars = Math.floor(frame / charFrames);
+	} else if (frame < preLen * charFrames + pauseFrames) {
+		typedChars = preLen;
+	} else {
+		const postPhase = frame - preLen * charFrames - pauseFrames;
+		typedChars = Math.min(
+			fullText.length,
+			preLen + Math.floor(postPhase / charFrames),
+		);
+	}
+	return fullText.slice(0, typedChars);
+};
+
+const Cursor: React.FC<{
+	frame: number;
+	blinkFrames: number;
+	symbol?: string;
+}> = ({frame, blinkFrames, symbol = '\u258C'}) => {
+	const opacity = interpolate(
+		frame % blinkFrames,
+		[0, blinkFrames / 2, blinkFrames],
+		[1, 0, 1],
+		{extrapolateLeft: 'clamp', extrapolateRight: 'clamp'},
+	);
+
+	return <span style={{opacity}}>{symbol}</span>;
+};
+
+export const MyAnimation = () => {
+	const frame = useCurrentFrame();
+	const {fps} = useVideoConfig();
+
+	const pauseFrames = Math.round(fps * PAUSE_SECONDS);
+
+	const typedText = getTypedText({
+		frame,
+		fullText: FULL_TEXT,
+		pauseAfter: PAUSE_AFTER,
+		charFrames: CHAR_FRAMES,
+		pauseFrames,
+	});
+
+	return (
+		<AbsoluteFill
+			style={{
+				backgroundColor: COLOR_BG,
+			}}
+		>
+			<div
+				style={{
+					color: COLOR_TEXT,
+					fontSize: FONT_SIZE,
+					fontWeight: FONT_WEIGHT,
+					fontFamily: 'sans-serif',
+				}}
+			>
+				<span>{typedText}</span>
+				<Cursor frame={frame} blinkFrames={CURSOR_BLINK_FRAMES} />
+			</div>
+		</AbsoluteFill>
+	);
+};

.agents/skills/remotion-best-practices/rules/assets/text-animations-word-highlight.tsx

@@ -0,0 +1,103 @@
+import {loadFont} from '@remotion/google-fonts/Inter';
+import React from 'react';
+import {AbsoluteFill, spring, useCurrentFrame, useVideoConfig} from 'remotion';
+
+/*
+ * Highlight a word in a sentence with a spring-animated wipe effect.
+ */
+
+// Ideal composition size: 1280x720
+
+const COLOR_BG = '#ffffff';
+const COLOR_TEXT = '#000000';
+const COLOR_HIGHLIGHT = '#A7C7E7';
+const FULL_TEXT = 'This is Remotion.';
+const HIGHLIGHT_WORD = 'Remotion';
+const FONT_SIZE = 72;
+const FONT_WEIGHT = 700;
+const HIGHLIGHT_START_FRAME = 30;
+const HIGHLIGHT_WIPE_DURATION = 18;
+
+const {fontFamily} = loadFont();
+
+const Highlight: React.FC<{
+	word: string;
+	color: string;
+	delay: number;
+	durationInFrames: number;
+}> = ({word, color, delay, durationInFrames}) => {
+	const frame = useCurrentFrame();
+	const {fps} = useVideoConfig();
+
+	const highlightProgress = spring({
+		fps,
+		frame,
+		config: {damping: 200},
+		delay,
+		durationInFrames,
+	});
+	const scaleX = Math.max(0, Math.min(1, highlightProgress));
+
+	return (
+		<span style={{position: 'relative', display: 'inline-block'}}>
+			<span
+				style={{
+					position: 'absolute',
+					left: 0,
+					right: 0,
+					top: '50%',
+					height: '1.05em',
+					transform: `translateY(-50%) scaleX(${scaleX})`,
+					transformOrigin: 'left center',
+					backgroundColor: color,
+					borderRadius: '0.18em',
+					zIndex: 0,
+				}}
+			/>
+			<span style={{position: 'relative', zIndex: 1}}>{word}</span>
+		</span>
+	);
+};
+
+export const MyAnimation = () => {
+	const highlightIndex = FULL_TEXT.indexOf(HIGHLIGHT_WORD);
+	const hasHighlight = highlightIndex >= 0;
+	const preText = hasHighlight ? FULL_TEXT.slice(0, highlightIndex) : FULL_TEXT;
+	const postText = hasHighlight
+		? FULL_TEXT.slice(highlightIndex + HIGHLIGHT_WORD.length)
+		: '';
+
+	return (
+		<AbsoluteFill
+			style={{
+				backgroundColor: COLOR_BG,
+				alignItems: 'center',
+				justifyContent: 'center',
+				fontFamily,
+			}}
+		>
+			<div
+				style={{
+					color: COLOR_TEXT,
+					fontSize: FONT_SIZE,
+					fontWeight: FONT_WEIGHT,
+				}}
+			>
+				{hasHighlight ? (
+					<>
+						<span>{preText}</span>
+						<Highlight
+							word={HIGHLIGHT_WORD}
+							color={COLOR_HIGHLIGHT}
+							delay={HIGHLIGHT_START_FRAME}
+							durationInFrames={HIGHLIGHT_WIPE_DURATION}
+						/>
+						<span>{postText}</span>
+					</>
+				) : (
+					<span>{FULL_TEXT}</span>
+				)}
+			</div>
+		</AbsoluteFill>
+	);
+};

.agents/skills/remotion-best-practices/rules/audio-visualization.md

@@ -0,0 +1,198 @@
+---
+name: audio-visualization
+description: Audio visualization patterns - spectrum bars, waveforms, bass-reactive effects
+metadata:
+  tags: audio, visualization, spectrum, waveform, bass, music, audiogram, frequency
+---
+
+# Audio Visualization in Remotion
+
+## Prerequisites
+
+```bash
+npx remotion add @remotion/media-utils
+```
+
+## Loading Audio Data
+
+Use `useWindowedAudioData()` (https://www.remotion.dev/docs/use-windowed-audio-data) to load audio data:
+
+```tsx
+import { useWindowedAudioData } from "@remotion/media-utils";
+import { staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+const { audioData, dataOffsetInSeconds } = useWindowedAudioData({
+  src: staticFile("podcast.wav"),
+  frame,
+  fps,
+  windowInSeconds: 30,
+});
+```
+
+## Spectrum Bar Visualization
+
+Use `visualizeAudio()` (https://www.remotion.dev/docs/visualize-audio) to get frequency data for bar charts:
+
+```tsx
+import { useWindowedAudioData, visualizeAudio } from "@remotion/media-utils";
+import { staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+const { audioData, dataOffsetInSeconds } = useWindowedAudioData({
+  src: staticFile("music.mp3"),
+  frame,
+  fps,
+  windowInSeconds: 30,
+});
+
+if (!audioData) {
+  return null;
+}
+
+const frequencies = visualizeAudio({
+  fps,
+  frame,
+  audioData,
+  numberOfSamples: 256,
+  optimizeFor: "speed",
+  dataOffsetInSeconds,
+});
+
+return (
+  <div style={{ display: "flex", alignItems: "flex-end", height: 200 }}>
+    {frequencies.map((v, i) => (
+      <div
+        key={i}
+        style={{
+          flex: 1,
+          height: `${v * 100}%`,
+          backgroundColor: "#0b84f3",
+          margin: "0 1px",
+        }}
+      />
+    ))}
+  </div>
+);
+```
+
+- `numberOfSamples` must be power of 2 (32, 64, 128, 256, 512, 1024)
+- Values range 0-1; left of array = bass, right = highs
+- Use `optimizeFor: "speed"` for Lambda or high sample counts
+
+**Important:** When passing `audioData` to child components, also pass the `frame` from the parent. Do not call `useCurrentFrame()` in each child - this causes discontinuous visualization when children are inside `<Sequence>` with offsets.
+
+## Waveform Visualization
+
+Use `visualizeAudioWaveform()` (https://www.remotion.dev/docs/media-utils/visualize-audio-waveform) with `createSmoothSvgPath()` (https://www.remotion.dev/docs/media-utils/create-smooth-svg-path) for oscilloscope-style displays:
+
+```tsx
+import {
+  createSmoothSvgPath,
+  useWindowedAudioData,
+  visualizeAudioWaveform,
+} from "@remotion/media-utils";
+import { staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+
+const frame = useCurrentFrame();
+const { width, fps } = useVideoConfig();
+const HEIGHT = 200;
+
+const { audioData, dataOffsetInSeconds } = useWindowedAudioData({
+  src: staticFile("voice.wav"),
+  frame,
+  fps,
+  windowInSeconds: 30,
+});
+
+if (!audioData) {
+  return null;
+}
+
+const waveform = visualizeAudioWaveform({
+  fps,
+  frame,
+  audioData,
+  numberOfSamples: 256,
+  windowInSeconds: 0.5,
+  dataOffsetInSeconds,
+});
+
+const path = createSmoothSvgPath({
+  points: waveform.map((y, i) => ({
+    x: (i / (waveform.length - 1)) * width,
+    y: HEIGHT / 2 + (y * HEIGHT) / 2,
+  })),
+});
+
+return (
+  <svg width={width} height={HEIGHT}>
+    <path d={path} fill="none" stroke="#0b84f3" strokeWidth={2} />
+  </svg>
+);
+```
+
+## Bass-Reactive Effects
+
+Extract low frequencies for beat-reactive animations:
+
+```tsx
+const frequencies = visualizeAudio({
+  fps,
+  frame,
+  audioData,
+  numberOfSamples: 128,
+  optimizeFor: "speed",
+  dataOffsetInSeconds,
+});
+
+const lowFrequencies = frequencies.slice(0, 32);
+const bassIntensity =
+  lowFrequencies.reduce((sum, v) => sum + v, 0) / lowFrequencies.length;
+
+const scale = 1 + bassIntensity * 0.5;
+const opacity = Math.min(0.6, bassIntensity * 0.8);
+```
+
+## Volume-Based Waveform
+
+Use `getWaveformPortion()` (https://www.remotion.dev/docs/get-waveform-portion) when you need simplified volume data instead of frequency spectrum:
+
+```tsx
+import { getWaveformPortion } from "@remotion/media-utils";
+import { useCurrentFrame, useVideoConfig } from "remotion";
+
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+const currentTimeInSeconds = frame / fps;
+
+const waveform = getWaveformPortion({
+  audioData,
+  startTimeInSeconds: currentTimeInSeconds,
+  durationInSeconds: 5,
+  numberOfSamples: 50,
+});
+
+// Returns array of { index, amplitude } objects (amplitude: 0-1)
+waveform.map((bar) => (
+  <div key={bar.index} style={{ height: bar.amplitude * 100 }} />
+));
+```
+
+## Postprocessing
+
+Low frequencies naturally dominate. Apply logarithmic scaling for visual balance:
+
+```tsx
+const minDb = -100;
+const maxDb = -30;
+
+const scaled = frequencies.map((value) => {
+  const db = 20 * Math.log10(value);
+  return (db - minDb) / (maxDb - minDb);
+});
+```

.agents/skills/remotion-best-practices/rules/audio.md

@@ -0,0 +1,169 @@
+---
+name: audio
+description: Using audio and sound in Remotion - importing, trimming, volume, speed, pitch
+metadata:
+  tags: audio, media, trim, volume, speed, loop, pitch, mute, sound, sfx
+---
+
+# Using audio in Remotion
+
+## Prerequisites
+
+First, the @remotion/media package needs to be installed.
+If it is not installed, use the following command:
+
+```bash
+npx remotion add @remotion/media
+```
+
+## Importing Audio
+
+Use `<Audio>` from `@remotion/media` to add audio to your composition.
+
+```tsx
+import { Audio } from "@remotion/media";
+import { staticFile } from "remotion";
+
+export const MyComposition = () => {
+  return <Audio src={staticFile("audio.mp3")} />;
+};
+```
+
+Remote URLs are also supported:
+
+```tsx
+<Audio src="https://remotion.media/audio.mp3" />
+```
+
+By default, audio plays from the start, at full volume and full length.
+Multiple audio tracks can be layered by adding multiple `<Audio>` components.
+
+## Trimming
+
+Use `trimBefore` and `trimAfter` to remove portions of the audio. Values are in frames.
+
+```tsx
+const { fps } = useVideoConfig();
+
+return (
+  <Audio
+    src={staticFile("audio.mp3")}
+    trimBefore={2 * fps} // Skip the first 2 seconds
+    trimAfter={10 * fps} // End at the 10 second mark
+  />
+);
+```
+
+The audio still starts playing at the beginning of the composition - only the specified portion is played.
+
+## Delaying
+
+Wrap the audio in a `<Sequence>` to delay when it starts:
+
+```tsx
+import { Sequence, staticFile } from "remotion";
+import { Audio } from "@remotion/media";
+
+const { fps } = useVideoConfig();
+
+return (
+  <Sequence from={1 * fps}>
+    <Audio src={staticFile("audio.mp3")} />
+  </Sequence>
+);
+```
+
+The audio will start playing after 1 second.
+
+## Volume
+
+Set a static volume (0 to 1):
+
+```tsx
+<Audio src={staticFile("audio.mp3")} volume={0.5} />
+```
+
+Or use a callback for dynamic volume based on the current frame:
+
+```tsx
+import { interpolate } from "remotion";
+
+const { fps } = useVideoConfig();
+
+return (
+  <Audio
+    src={staticFile("audio.mp3")}
+    volume={(f) =>
+      interpolate(f, [0, 1 * fps], [0, 1], { extrapolateRight: "clamp" })
+    }
+  />
+);
+```
+
+The value of `f` starts at 0 when the audio begins to play, not the composition frame.
+
+## Muting
+
+Use `muted` to silence the audio. It can be set dynamically:
+
+```tsx
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+return (
+  <Audio
+    src={staticFile("audio.mp3")}
+    muted={frame >= 2 * fps && frame <= 4 * fps} // Mute between 2s and 4s
+  />
+);
+```
+
+## Speed
+
+Use `playbackRate` to change the playback speed:
+
+```tsx
+<Audio src={staticFile("audio.mp3")} playbackRate={2} /> {/* 2x speed */}
+<Audio src={staticFile("audio.mp3")} playbackRate={0.5} /> {/* Half speed */}
+```
+
+Reverse playback is not supported.
+
+## Looping
+
+Use `loop` to loop the audio indefinitely:
+
+```tsx
+<Audio src={staticFile("audio.mp3")} loop />
+```
+
+Use `loopVolumeCurveBehavior` to control how the frame count behaves when looping:
+
+- `"repeat"`: Frame count resets to 0 each loop (default)
+- `"extend"`: Frame count continues incrementing
+
+```tsx
+<Audio
+  src={staticFile("audio.mp3")}
+  loop
+  loopVolumeCurveBehavior="extend"
+  volume={(f) => interpolate(f, [0, 300], [1, 0])} // Fade out over multiple loops
+/>
+```
+
+## Pitch
+
+Use `toneFrequency` to adjust the pitch without affecting speed. Values range from 0.01 to 2:
+
+```tsx
+<Audio
+  src={staticFile("audio.mp3")}
+  toneFrequency={1.5} // Higher pitch
+/>
+<Audio
+  src={staticFile("audio.mp3")}
+  toneFrequency={0.8} // Lower pitch
+/>
+```
+
+Pitch shifting only works during server-side rendering, not in the Remotion Studio preview or in the `<Player />`.

.agents/skills/remotion-best-practices/rules/calculate-metadata.md

@@ -0,0 +1,134 @@
+---
+name: calculate-metadata
+description: Dynamically set composition duration, dimensions, and props
+metadata:
+  tags: calculateMetadata, duration, dimensions, props, dynamic
+---
+
+# Using calculateMetadata
+
+Use `calculateMetadata` on a `<Composition>` to dynamically set duration, dimensions, and transform props before rendering.
+
+```tsx
+<Composition
+  id="MyComp"
+  component={MyComponent}
+  durationInFrames={300}
+  fps={30}
+  width={1920}
+  height={1080}
+  defaultProps={{ videoSrc: "https://remotion.media/video.mp4" }}
+  calculateMetadata={calculateMetadata}
+/>
+```
+
+## Setting duration based on a video
+
+Use the [`getVideoDuration`](./get-video-duration.md) and [`getVideoDimensions`](./get-video-dimensions.md) skills to get the video duration and dimensions:
+
+```tsx
+import { CalculateMetadataFunction } from "remotion";
+import { getVideoDuration } from "./get-video-duration";
+
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  const durationInSeconds = await getVideoDuration(props.videoSrc);
+
+  return {
+    durationInFrames: Math.ceil(durationInSeconds * 30),
+  };
+};
+```
+
+## Matching dimensions of a video
+
+Use the [`getVideoDimensions`](./get-video-dimensions.md) skill to get the video dimensions:
+
+```tsx
+import { CalculateMetadataFunction } from "remotion";
+import { getVideoDuration } from "./get-video-duration";
+import { getVideoDimensions } from "./get-video-dimensions";
+
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  const dimensions = await getVideoDimensions(props.videoSrc);
+
+  return {
+    width: dimensions.width,
+    height: dimensions.height,
+  };
+};
+```
+
+## Setting duration based on multiple videos
+
+```tsx
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  const metadataPromises = props.videos.map((video) =>
+    getVideoDuration(video.src),
+  );
+  const allMetadata = await Promise.all(metadataPromises);
+
+  const totalDuration = allMetadata.reduce(
+    (sum, durationInSeconds) => sum + durationInSeconds,
+    0,
+  );
+
+  return {
+    durationInFrames: Math.ceil(totalDuration * 30),
+  };
+};
+```
+
+## Setting a default outName
+
+Set the default output filename based on props:
+
+```tsx
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  return {
+    defaultOutName: `video-${props.id}.mp4`,
+  };
+};
+```
+
+## Transforming props
+
+Fetch data or transform props before rendering:
+
+```tsx
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+  abortSignal,
+}) => {
+  const response = await fetch(props.dataUrl, { signal: abortSignal });
+  const data = await response.json();
+
+  return {
+    props: {
+      ...props,
+      fetchedData: data,
+    },
+  };
+};
+```
+
+The `abortSignal` cancels stale requests when props change in the Studio.
+
+## Return value
+
+All fields are optional. Returned values override the `<Composition>` props:
+
+- `durationInFrames`: Number of frames
+- `width`: Composition width in pixels
+- `height`: Composition height in pixels
+- `fps`: Frames per second
+- `props`: Transformed props passed to the component
+- `defaultOutName`: Default output filename
+- `defaultCodec`: Default codec for rendering

.agents/skills/remotion-best-practices/rules/can-decode.md

@@ -0,0 +1,75 @@
+---
+name: can-decode
+description: Check if a video can be decoded by the browser using Mediabunny
+metadata:
+  tags: decode, validation, video, audio, compatibility, browser
+---
+
+# Checking if a video can be decoded
+
+Use Mediabunny to check if a video can be decoded by the browser before attempting to play it.
+
+## The `canDecode()` function
+
+This function can be copy-pasted into any project.
+
+```tsx
+import { Input, ALL_FORMATS, UrlSource } from "mediabunny";
+
+export const canDecode = async (src: string) => {
+  const input = new Input({
+    formats: ALL_FORMATS,
+    source: new UrlSource(src, {
+      getRetryDelay: () => null,
+    }),
+  });
+
+  try {
+    await input.getFormat();
+  } catch {
+    return false;
+  }
+
+  const videoTrack = await input.getPrimaryVideoTrack();
+  if (videoTrack && !(await videoTrack.canDecode())) {
+    return false;
+  }
+
+  const audioTrack = await input.getPrimaryAudioTrack();
+  if (audioTrack && !(await audioTrack.canDecode())) {
+    return false;
+  }
+
+  return true;
+};
+```
+
+## Usage
+
+```tsx
+const src = "https://remotion.media/video.mp4";
+const isDecodable = await canDecode(src);
+
+if (isDecodable) {
+  console.log("Video can be decoded");
+} else {
+  console.log("Video cannot be decoded by this browser");
+}
+```
+
+## Using with Blob
+
+For file uploads or drag-and-drop, use `BlobSource`:
+
+```tsx
+import { Input, ALL_FORMATS, BlobSource } from "mediabunny";
+
+export const canDecodeBlob = async (blob: Blob) => {
+  const input = new Input({
+    formats: ALL_FORMATS,
+    source: new BlobSource(blob),
+  });
+
+  // Same validation logic as above
+};
+```

.agents/skills/remotion-best-practices/rules/charts.md

@@ -0,0 +1,120 @@
+---
+name: charts
+description: Chart and data visualization patterns for Remotion. Use when creating bar charts, pie charts, line charts, stock graphs, or any data-driven animations.
+metadata:
+  tags: charts, data, visualization, bar-chart, pie-chart, line-chart, stock-chart, svg-paths, graphs
+---
+
+# Charts in Remotion
+
+Create charts using React code - HTML, SVG, and D3.js are all supported.
+
+Disable all animations from third party libraries - they cause flickering.  
+Drive all animations from `useCurrentFrame()`.
+
+## Bar Chart
+
+```tsx
+const STAGGER_DELAY = 5;
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+const bars = data.map((item, i) => {
+  const height = spring({
+    frame,
+    fps,
+    delay: i * STAGGER_DELAY,
+    config: { damping: 200 },
+  });
+  return <div style={{ height: height * item.value }} />;
+});
+```
+
+## Pie Chart
+
+Animate segments using stroke-dashoffset, starting from 12 o'clock:
+
+```tsx
+const progress = interpolate(frame, [0, 100], [0, 1]);
+const circumference = 2 * Math.PI * radius;
+const segmentLength = (value / total) * circumference;
+const offset = interpolate(progress, [0, 1], [segmentLength, 0]);
+
+<circle
+  r={radius}
+  cx={center}
+  cy={center}
+  fill="none"
+  stroke={color}
+  strokeWidth={strokeWidth}
+  strokeDasharray={`${segmentLength} ${circumference}`}
+  strokeDashoffset={offset}
+  transform={`rotate(-90 ${center} ${center})`}
+/>;
+```
+
+## Line Chart / Path Animation
+
+Use `@remotion/paths` for animating SVG paths (line charts, stock graphs, signatures).
+
+Install: `npx remotion add @remotion/paths`  
+Docs: https://remotion.dev/docs/paths.md
+
+### Convert data points to SVG path
+
+```tsx
+type Point = { x: number; y: number };
+
+const generateLinePath = (points: Point[]): string => {
+  if (points.length < 2) return "";
+  return points.map((p, i) => `${i === 0 ? "M" : "L"} ${p.x} ${p.y}`).join(" ");
+};
+```
+
+### Draw path with animation
+
+```tsx
+import { evolvePath } from "@remotion/paths";
+
+const path = "M 100 200 L 200 150 L 300 180 L 400 100";
+const progress = interpolate(frame, [0, 2 * fps], [0, 1], {
+  extrapolateLeft: "clamp",
+  extrapolateRight: "clamp",
+  easing: Easing.out(Easing.quad),
+});
+
+const { strokeDasharray, strokeDashoffset } = evolvePath(progress, path);
+
+<path
+  d={path}
+  fill="none"
+  stroke="#FF3232"
+  strokeWidth={4}
+  strokeDasharray={strokeDasharray}
+  strokeDashoffset={strokeDashoffset}
+/>;
+```
+
+### Follow path with marker/arrow
+
+```tsx
+import {
+  getLength,
+  getPointAtLength,
+  getTangentAtLength,
+} from "@remotion/paths";
+
+const pathLength = getLength(path);
+const point = getPointAtLength(path, progress * pathLength);
+const tangent = getTangentAtLength(path, progress * pathLength);
+const angle = Math.atan2(tangent.y, tangent.x);
+
+<g
+  style={{
+    transform: `translate(${point.x}px, ${point.y}px) rotate(${angle}rad)`,
+    transformOrigin: "0 0",
+  }}
+>
+  <polygon points="0,0 -20,-10 -20,10" fill="#FF3232" />
+</g>;
+```

.agents/skills/remotion-best-practices/rules/compositions.md

@@ -0,0 +1,154 @@
+---
+name: compositions
+description: Defining compositions, stills, folders, default props and dynamic metadata
+metadata:
+  tags: composition, still, folder, props, metadata
+---
+
+A `<Composition>` defines the component, width, height, fps and duration of a renderable video.
+
+It normally is placed in the `src/Root.tsx` file.
+
+```tsx
+import { Composition } from "remotion";
+import { MyComposition } from "./MyComposition";
+
+export const RemotionRoot = () => {
+  return (
+    <Composition
+      id="MyComposition"
+      component={MyComposition}
+      durationInFrames={100}
+      fps={30}
+      width={1080}
+      height={1080}
+    />
+  );
+};
+```
+
+## Default Props
+
+Pass `defaultProps` to provide initial values for your component.  
+Values must be JSON-serializable (`Date`, `Map`, `Set`, and `staticFile()` are supported).
+
+```tsx
+import { Composition } from "remotion";
+import { MyComposition, MyCompositionProps } from "./MyComposition";
+
+export const RemotionRoot = () => {
+  return (
+    <Composition
+      id="MyComposition"
+      component={MyComposition}
+      durationInFrames={100}
+      fps={30}
+      width={1080}
+      height={1080}
+      defaultProps={
+        {
+          title: "Hello World",
+          color: "#ff0000",
+        } satisfies MyCompositionProps
+      }
+    />
+  );
+};
+```
+
+Use `type` declarations for props rather than `interface` to ensure `defaultProps` type safety.
+
+## Folders
+
+Use `<Folder>` to organize compositions in the sidebar.  
+Folder names can only contain letters, numbers, and hyphens.
+
+```tsx
+import { Composition, Folder } from "remotion";
+
+export const RemotionRoot = () => {
+  return (
+    <>
+      <Folder name="Marketing">
+        <Composition id="Promo" /* ... */ />
+        <Composition id="Ad" /* ... */ />
+      </Folder>
+      <Folder name="Social">
+        <Folder name="Instagram">
+          <Composition id="Story" /* ... */ />
+          <Composition id="Reel" /* ... */ />
+        </Folder>
+      </Folder>
+    </>
+  );
+};
+```
+
+## Stills
+
+Use `<Still>` for single-frame images. It does not require `durationInFrames` or `fps`.
+
+```tsx
+import { Still } from "remotion";
+import { Thumbnail } from "./Thumbnail";
+
+export const RemotionRoot = () => {
+  return (
+    <Still id="Thumbnail" component={Thumbnail} width={1280} height={720} />
+  );
+};
+```
+
+## Calculate Metadata
+
+Use `calculateMetadata` to make dimensions, duration, or props dynamic based on data.
+
+```tsx
+import { Composition, CalculateMetadataFunction } from "remotion";
+import { MyComposition, MyCompositionProps } from "./MyComposition";
+
+const calculateMetadata: CalculateMetadataFunction<
+  MyCompositionProps
+> = async ({ props, abortSignal }) => {
+  const data = await fetch(`https://api.example.com/video/${props.videoId}`, {
+    signal: abortSignal,
+  }).then((res) => res.json());
+
+  return {
+    durationInFrames: Math.ceil(data.duration * 30),
+    props: {
+      ...props,
+      videoUrl: data.url,
+    },
+  };
+};
+
+export const RemotionRoot = () => {
+  return (
+    <Composition
+      id="MyComposition"
+      component={MyComposition}
+      durationInFrames={100} // Placeholder, will be overridden
+      fps={30}
+      width={1080}
+      height={1080}
+      defaultProps={{ videoId: "abc123" }}
+      calculateMetadata={calculateMetadata}
+    />
+  );
+};
+```
+
+The function can return `props`, `durationInFrames`, `width`, `height`, `fps`, and codec-related defaults. It runs once before rendering begins.
+
+## Nesting compositions within another
+
+To add a composition within another composition, you can use the `<Sequence>` component with a `width` and `height` prop to specify the size of the composition.
+
+```tsx
+<AbsoluteFill>
+  <Sequence width={COMPOSITION_WIDTH} height={COMPOSITION_HEIGHT}>
+    <CompositionComponent />
+  </Sequence>
+</AbsoluteFill>
+```

.agents/skills/remotion-best-practices/rules/display-captions.md

@@ -0,0 +1,184 @@
+---
+name: display-captions
+description: Displaying captions in Remotion with TikTok-style pages and word highlighting
+metadata:
+  tags: captions, subtitles, display, tiktok, highlight
+---
+
+# Displaying captions in Remotion
+
+This guide explains how to display captions in Remotion, assuming you already have captions in the [`Caption`](https://www.remotion.dev/docs/captions/caption) format.
+
+## Prerequisites
+
+Read [Transcribing audio](transcribe-captions.md) for how to generate captions.
+
+First, the [`@remotion/captions`](https://www.remotion.dev/docs/captions) package needs to be installed.
+If it is not installed, use the following command:
+
+```bash
+npx remotion add @remotion/captions
+```
+
+## Fetching captions
+
+First, fetch your captions JSON file. Use [`useDelayRender()`](https://www.remotion.dev/docs/use-delay-render) to hold the render until the captions are loaded:
+
+```tsx
+import { useState, useEffect, useCallback } from "react";
+import { AbsoluteFill, staticFile, useDelayRender } from "remotion";
+import type { Caption } from "@remotion/captions";
+
+export const MyComponent: React.FC = () => {
+  const [captions, setCaptions] = useState<Caption[] | null>(null);
+  const { delayRender, continueRender, cancelRender } = useDelayRender();
+  const [handle] = useState(() => delayRender());
+
+  const fetchCaptions = useCallback(async () => {
+    try {
+      // Assuming captions.json is in the public/ folder.
+      const response = await fetch(staticFile("captions123.json"));
+      const data = await response.json();
+      setCaptions(data);
+      continueRender(handle);
+    } catch (e) {
+      cancelRender(e);
+    }
+  }, [continueRender, cancelRender, handle]);
+
+  useEffect(() => {
+    fetchCaptions();
+  }, [fetchCaptions]);
+
+  if (!captions) {
+    return null;
+  }
+
+  return <AbsoluteFill>{/* Render captions here */}</AbsoluteFill>;
+};
+```
+
+## Creating pages
+
+Use `createTikTokStyleCaptions()` to group captions into pages. The `combineTokensWithinMilliseconds` option controls how many words appear at once:
+
+```tsx
+import { useMemo } from "react";
+import { createTikTokStyleCaptions } from "@remotion/captions";
+import type { Caption } from "@remotion/captions";
+
+// How often captions should switch (in milliseconds)
+// Higher values = more words per page
+// Lower values = fewer words (more word-by-word)
+const SWITCH_CAPTIONS_EVERY_MS = 1200;
+
+const { pages } = useMemo(() => {
+  return createTikTokStyleCaptions({
+    captions,
+    combineTokensWithinMilliseconds: SWITCH_CAPTIONS_EVERY_MS,
+  });
+}, [captions]);
+```
+
+## Rendering with Sequences
+
+Map over the pages and render each one in a `<Sequence>`. Calculate the start frame and duration from the page timing:
+
+```tsx
+import { Sequence, useVideoConfig, AbsoluteFill } from "remotion";
+import type { TikTokPage } from "@remotion/captions";
+
+const CaptionedContent: React.FC = () => {
+  const { fps } = useVideoConfig();
+
+  return (
+    <AbsoluteFill>
+      {pages.map((page, index) => {
+        const nextPage = pages[index + 1] ?? null;
+        const startFrame = (page.startMs / 1000) * fps;
+        const endFrame = Math.min(
+          nextPage ? (nextPage.startMs / 1000) * fps : Infinity,
+          startFrame + (SWITCH_CAPTIONS_EVERY_MS / 1000) * fps,
+        );
+        const durationInFrames = endFrame - startFrame;
+
+        if (durationInFrames <= 0) {
+          return null;
+        }
+
+        return (
+          <Sequence
+            key={index}
+            from={startFrame}
+            durationInFrames={durationInFrames}
+          >
+            <CaptionPage page={page} />
+          </Sequence>
+        );
+      })}
+    </AbsoluteFill>
+  );
+};
+```
+
+## White-space preservation
+
+The captions are whitespace sensitive. You should include spaces in the `text` field before each word. Use `whiteSpace: "pre"` to preserve the whitespace in the captions.
+
+## Separate component for captions
+
+Put captioning logic in a separate component.  
+Make a new file for it.
+
+## Word highlighting
+
+A caption page contains `tokens` which you can use to highlight the currently spoken word:
+
+```tsx
+import { AbsoluteFill, useCurrentFrame, useVideoConfig } from "remotion";
+import type { TikTokPage } from "@remotion/captions";
+
+const HIGHLIGHT_COLOR = "#39E508";
+
+const CaptionPage: React.FC<{ page: TikTokPage }> = ({ page }) => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+
+  // Current time relative to the start of the sequence
+  const currentTimeMs = (frame / fps) * 1000;
+  // Convert to absolute time by adding the page start
+  const absoluteTimeMs = page.startMs + currentTimeMs;
+
+  return (
+    <AbsoluteFill style={{ justifyContent: "center", alignItems: "center" }}>
+      <div style={{ fontSize: 80, fontWeight: "bold", whiteSpace: "pre" }}>
+        {page.tokens.map((token) => {
+          const isActive =
+            token.fromMs <= absoluteTimeMs && token.toMs > absoluteTimeMs;
+
+          return (
+            <span
+              key={token.fromMs}
+              style={{ color: isActive ? HIGHLIGHT_COLOR : "white" }}
+            >
+              {token.text}
+            </span>
+          );
+        })}
+      </div>
+    </AbsoluteFill>
+  );
+};
+```
+
+## Display captions alongside video content
+
+By default, put the captions alongside the video content, so the captions are in sync.  
+For each video, make a new captions JSON file.
+
+```tsx
+<AbsoluteFill>
+  <Video src={staticFile("video.mp4")} />
+  <CaptionPage page={page} />
+</AbsoluteFill>
+```

.agents/skills/remotion-best-practices/rules/extract-frames.md

@@ -0,0 +1,229 @@
+---
+name: extract-frames
+description: Extract frames from videos at specific timestamps using Mediabunny
+metadata:
+  tags: frames, extract, video, thumbnail, filmstrip, canvas
+---
+
+# Extracting frames from videos
+
+Use Mediabunny to extract frames from videos at specific timestamps. This is useful for generating thumbnails, filmstrips, or processing individual frames.
+
+## The `extractFrames()` function
+
+This function can be copy-pasted into any project.
+
+```tsx
+import {
+  ALL_FORMATS,
+  Input,
+  UrlSource,
+  VideoSample,
+  VideoSampleSink,
+} from "mediabunny";
+
+type Options = {
+  track: { width: number; height: number };
+  container: string;
+  durationInSeconds: number | null;
+};
+
+export type ExtractFramesTimestampsInSecondsFn = (
+  options: Options,
+) => Promise<number[]> | number[];
+
+export type ExtractFramesProps = {
+  src: string;
+  timestampsInSeconds: number[] | ExtractFramesTimestampsInSecondsFn;
+  onVideoSample: (sample: VideoSample) => void;
+  signal?: AbortSignal;
+};
+
+export async function extractFrames({
+  src,
+  timestampsInSeconds,
+  onVideoSample,
+  signal,
+}: ExtractFramesProps): Promise<void> {
+  using input = new Input({
+    formats: ALL_FORMATS,
+    source: new UrlSource(src),
+  });
+
+  const [durationInSeconds, format, videoTrack] = await Promise.all([
+    input.computeDuration(),
+    input.getFormat(),
+    input.getPrimaryVideoTrack(),
+  ]);
+
+  if (!videoTrack) {
+    throw new Error("No video track found in the input");
+  }
+
+  if (signal?.aborted) {
+    throw new Error("Aborted");
+  }
+
+  const timestamps =
+    typeof timestampsInSeconds === "function"
+      ? await timestampsInSeconds({
+          track: {
+            width: videoTrack.displayWidth,
+            height: videoTrack.displayHeight,
+          },
+          container: format.name,
+          durationInSeconds,
+        })
+      : timestampsInSeconds;
+
+  if (timestamps.length === 0) {
+    return;
+  }
+
+  if (signal?.aborted) {
+    throw new Error("Aborted");
+  }
+
+  const sink = new VideoSampleSink(videoTrack);
+
+  for await (using videoSample of sink.samplesAtTimestamps(timestamps)) {
+    if (signal?.aborted) {
+      break;
+    }
+
+    if (!videoSample) {
+      continue;
+    }
+
+    onVideoSample(videoSample);
+  }
+}
+```
+
+## Basic usage
+
+Extract frames at specific timestamps:
+
+```tsx
+await extractFrames({
+  src: "https://remotion.media/video.mp4",
+  timestampsInSeconds: [0, 1, 2, 3, 4],
+  onVideoSample: (sample) => {
+    const canvas = document.createElement("canvas");
+    canvas.width = sample.displayWidth;
+    canvas.height = sample.displayHeight;
+    const ctx = canvas.getContext("2d");
+    sample.draw(ctx!, 0, 0);
+  },
+});
+```
+
+## Creating a filmstrip
+
+Use a callback function to dynamically calculate timestamps based on video metadata:
+
+```tsx
+const canvasWidth = 500;
+const canvasHeight = 80;
+const fromSeconds = 0;
+const toSeconds = 10;
+
+await extractFrames({
+  src: "https://remotion.media/video.mp4",
+  timestampsInSeconds: async ({ track, durationInSeconds }) => {
+    const aspectRatio = track.width / track.height;
+    const amountOfFramesFit = Math.ceil(
+      canvasWidth / (canvasHeight * aspectRatio),
+    );
+    const segmentDuration = toSeconds - fromSeconds;
+    const timestamps: number[] = [];
+
+    for (let i = 0; i < amountOfFramesFit; i++) {
+      timestamps.push(
+        fromSeconds + (segmentDuration / amountOfFramesFit) * (i + 0.5),
+      );
+    }
+
+    return timestamps;
+  },
+  onVideoSample: (sample) => {
+    console.log(`Frame at ${sample.timestamp}s`);
+
+    const canvas = document.createElement("canvas");
+    canvas.width = sample.displayWidth;
+    canvas.height = sample.displayHeight;
+    const ctx = canvas.getContext("2d");
+    sample.draw(ctx!, 0, 0);
+  },
+});
+```
+
+## Cancellation with AbortSignal
+
+Cancel frame extraction after a timeout:
+
+```tsx
+const controller = new AbortController();
+
+setTimeout(() => controller.abort(), 5000);
+
+try {
+  await extractFrames({
+    src: "https://remotion.media/video.mp4",
+    timestampsInSeconds: [0, 1, 2, 3, 4],
+    onVideoSample: (sample) => {
+      using frame = sample;
+      const canvas = document.createElement("canvas");
+      canvas.width = frame.displayWidth;
+      canvas.height = frame.displayHeight;
+      const ctx = canvas.getContext("2d");
+      frame.draw(ctx!, 0, 0);
+    },
+    signal: controller.signal,
+  });
+
+  console.log("Frame extraction complete!");
+} catch (error) {
+  console.error("Frame extraction was aborted or failed:", error);
+}
+```
+
+## Timeout with Promise.race
+
+```tsx
+const controller = new AbortController();
+
+const timeoutPromise = new Promise<never>((_, reject) => {
+  const timeoutId = setTimeout(() => {
+    controller.abort();
+    reject(new Error("Frame extraction timed out after 10 seconds"));
+  }, 10000);
+
+  controller.signal.addEventListener("abort", () => clearTimeout(timeoutId), {
+    once: true,
+  });
+});
+
+try {
+  await Promise.race([
+    extractFrames({
+      src: "https://remotion.media/video.mp4",
+      timestampsInSeconds: [0, 1, 2, 3, 4],
+      onVideoSample: (sample) => {
+        using frame = sample;
+        const canvas = document.createElement("canvas");
+        canvas.width = frame.displayWidth;
+        canvas.height = frame.displayHeight;
+        const ctx = canvas.getContext("2d");
+        frame.draw(ctx!, 0, 0);
+      },
+      signal: controller.signal,
+    }),
+    timeoutPromise,
+  ]);
+
+  console.log("Frame extraction complete!");
+} catch (error) {
+  console.error("Frame extraction was aborted or failed:", error);
+}
+```

.agents/skills/remotion-best-practices/rules/ffmpeg.md

@@ -0,0 +1,38 @@
+---
+name: ffmpeg
+description: Using FFmpeg and FFprobe in Remotion
+metadata:
+  tags: ffmpeg, ffprobe, video, trimming
+---
+
+## FFmpeg in Remotion
+
+`ffmpeg` and `ffprobe` do not need to be installed. They are available via the `bunx remotion ffmpeg` and `bunx remotion ffprobe`:
+
+```bash
+bunx remotion ffmpeg -i input.mp4 output.mp3
+bunx remotion ffprobe input.mp4
+```
+
+### Trimming videos
+
+You have 2 options for trimming videos:
+
+1. Use the FFMpeg command line. You MUST re-encode the video to avoid frozen frames at the start of the video.
+
+```bash
+# Re-encodes from the exact frame
+bunx remotion ffmpeg -ss 00:00:05 -i public/input.mp4 -to 00:00:10 -c:v libx264 -c:a aac public/output.mp4
+```
+
+2. Use the `trimBefore` and `trimAfter` props of the `<Video>` component. The benefit is that this is non-destructive and you can change the trim at any time.
+
+```tsx
+import { Video } from "@remotion/media";
+
+<Video
+  src={staticFile("video.mp4")}
+  trimBefore={5 * fps}
+  trimAfter={10 * fps}
+/>;
+```

.agents/skills/remotion-best-practices/rules/fonts.md

@@ -0,0 +1,152 @@
+---
+name: fonts
+description: Loading Google Fonts and local fonts in Remotion
+metadata:
+  tags: fonts, google-fonts, typography, text
+---
+
+# Using fonts in Remotion
+
+## Google Fonts with @remotion/google-fonts
+
+The recommended way to use Google Fonts. It's type-safe and automatically blocks rendering until the font is ready.
+
+### Prerequisites
+
+First, the @remotion/google-fonts package needs to be installed.
+If it is not installed, use the following command:
+
+```bash
+npx remotion add @remotion/google-fonts # If project uses npm
+bunx remotion add @remotion/google-fonts # If project uses bun
+yarn remotion add @remotion/google-fonts # If project uses yarn
+pnpm exec remotion add @remotion/google-fonts # If project uses pnpm
+```
+
+```tsx
+import { loadFont } from "@remotion/google-fonts/Lobster";
+
+const { fontFamily } = loadFont();
+
+export const MyComposition = () => {
+  return <div style={{ fontFamily }}>Hello World</div>;
+};
+```
+
+Preferrably, specify only needed weights and subsets to reduce file size:
+
+```tsx
+import { loadFont } from "@remotion/google-fonts/Roboto";
+
+const { fontFamily } = loadFont("normal", {
+  weights: ["400", "700"],
+  subsets: ["latin"],
+});
+```
+
+### Waiting for font to load
+
+Use `waitUntilDone()` if you need to know when the font is ready:
+
+```tsx
+import { loadFont } from "@remotion/google-fonts/Lobster";
+
+const { fontFamily, waitUntilDone } = loadFont();
+
+await waitUntilDone();
+```
+
+## Local fonts with @remotion/fonts
+
+For local font files, use the `@remotion/fonts` package.
+
+### Prerequisites
+
+First, install @remotion/fonts:
+
+```bash
+npx remotion add @remotion/fonts # If project uses npm
+bunx remotion add @remotion/fonts # If project uses bun
+yarn remotion add @remotion/fonts # If project uses yarn
+pnpm exec remotion add @remotion/fonts # If project uses pnpm
+```
+
+### Loading a local font
+
+Place your font file in the `public/` folder and use `loadFont()`:
+
+```tsx
+import { loadFont } from "@remotion/fonts";
+import { staticFile } from "remotion";
+
+await loadFont({
+  family: "MyFont",
+  url: staticFile("MyFont-Regular.woff2"),
+});
+
+export const MyComposition = () => {
+  return <div style={{ fontFamily: "MyFont" }}>Hello World</div>;
+};
+```
+
+### Loading multiple weights
+
+Load each weight separately with the same family name:
+
+```tsx
+import { loadFont } from "@remotion/fonts";
+import { staticFile } from "remotion";
+
+await Promise.all([
+  loadFont({
+    family: "Inter",
+    url: staticFile("Inter-Regular.woff2"),
+    weight: "400",
+  }),
+  loadFont({
+    family: "Inter",
+    url: staticFile("Inter-Bold.woff2"),
+    weight: "700",
+  }),
+]);
+```
+
+### Available options
+
+```tsx
+loadFont({
+  family: "MyFont", // Required: name to use in CSS
+  url: staticFile("font.woff2"), // Required: font file URL
+  format: "woff2", // Optional: auto-detected from extension
+  weight: "400", // Optional: font weight
+  style: "normal", // Optional: normal or italic
+  display: "block", // Optional: font-display behavior
+});
+```
+
+## Using in components
+
+Call `loadFont()` at the top level of your component or in a separate file that's imported early:
+
+```tsx
+import { loadFont } from "@remotion/google-fonts/Montserrat";
+
+const { fontFamily } = loadFont("normal", {
+  weights: ["400", "700"],
+  subsets: ["latin"],
+});
+
+export const Title: React.FC<{ text: string }> = ({ text }) => {
+  return (
+    <h1
+      style={{
+        fontFamily,
+        fontSize: 80,
+        fontWeight: "bold",
+      }}
+    >
+      {text}
+    </h1>
+  );
+};
+```

.agents/skills/remotion-best-practices/rules/get-audio-duration.md

@@ -0,0 +1,58 @@
+---
+name: get-audio-duration
+description: Getting the duration of an audio file in seconds with Mediabunny
+metadata:
+  tags: duration, audio, length, time, seconds, mp3, wav
+---
+
+# Getting audio duration with Mediabunny
+
+Mediabunny can extract the duration of an audio file. It works in browser, Node.js, and Bun environments.
+
+## Getting audio duration
+
+```tsx title="get-audio-duration.ts"
+import { Input, ALL_FORMATS, UrlSource } from "mediabunny";
+
+export const getAudioDuration = async (src: string) => {
+  const input = new Input({
+    formats: ALL_FORMATS,
+    source: new UrlSource(src, {
+      getRetryDelay: () => null,
+    }),
+  });
+
+  const durationInSeconds = await input.computeDuration();
+  return durationInSeconds;
+};
+```
+
+## Usage
+
+```tsx
+const duration = await getAudioDuration("https://remotion.media/audio.mp3");
+console.log(duration); // e.g. 180.5 (seconds)
+```
+
+## Using with staticFile in Remotion
+
+Make sure to wrap the file path in `staticFile()`:
+
+```tsx
+import { staticFile } from "remotion";
+
+const duration = await getAudioDuration(staticFile("audio.mp3"));
+```
+
+## In Node.js and Bun
+
+Use `FileSource` instead of `UrlSource`:
+
+```tsx
+import { Input, ALL_FORMATS, FileSource } from "mediabunny";
+
+const input = new Input({
+  formats: ALL_FORMATS,
+  source: new FileSource(file), // File object from input or drag-drop
+});
+```

.agents/skills/remotion-best-practices/rules/get-video-dimensions.md

@@ -0,0 +1,68 @@
+---
+name: get-video-dimensions
+description: Getting the width and height of a video file with Mediabunny
+metadata:
+  tags: dimensions, width, height, resolution, size, video
+---
+
+# Getting video dimensions with Mediabunny
+
+Mediabunny can extract the width and height of a video file. It works in browser, Node.js, and Bun environments.
+
+## Getting video dimensions
+
+```tsx
+import { Input, ALL_FORMATS, UrlSource } from "mediabunny";
+
+export const getVideoDimensions = async (src: string) => {
+  const input = new Input({
+    formats: ALL_FORMATS,
+    source: new UrlSource(src, {
+      getRetryDelay: () => null,
+    }),
+  });
+
+  const videoTrack = await input.getPrimaryVideoTrack();
+  if (!videoTrack) {
+    throw new Error("No video track found");
+  }
+
+  return {
+    width: videoTrack.displayWidth,
+    height: videoTrack.displayHeight,
+  };
+};
+```
+
+## Usage
+
+```tsx
+const dimensions = await getVideoDimensions("https://remotion.media/video.mp4");
+console.log(dimensions.width); // e.g. 1920
+console.log(dimensions.height); // e.g. 1080
+```
+
+## Using with local files
+
+For local files, use `FileSource` instead of `UrlSource`:
+
+```tsx
+import { Input, ALL_FORMATS, FileSource } from "mediabunny";
+
+const input = new Input({
+  formats: ALL_FORMATS,
+  source: new FileSource(file), // File object from input or drag-drop
+});
+
+const videoTrack = await input.getPrimaryVideoTrack();
+const width = videoTrack.displayWidth;
+const height = videoTrack.displayHeight;
+```
+
+## Using with staticFile in Remotion
+
+```tsx
+import { staticFile } from "remotion";
+
+const dimensions = await getVideoDimensions(staticFile("video.mp4"));
+```

.agents/skills/remotion-best-practices/rules/get-video-duration.md

@@ -0,0 +1,60 @@
+---
+name: get-video-duration
+description: Getting the duration of a video file in seconds with Mediabunny
+metadata:
+  tags: duration, video, length, time, seconds
+---
+
+# Getting video duration with Mediabunny
+
+Mediabunny can extract the duration of a video file. It works in browser, Node.js, and Bun environments.
+
+## Getting video duration
+
+```tsx
+import { Input, ALL_FORMATS, UrlSource } from "mediabunny";
+
+export const getVideoDuration = async (src: string) => {
+  const input = new Input({
+    formats: ALL_FORMATS,
+    source: new UrlSource(src, {
+      getRetryDelay: () => null,
+    }),
+  });
+
+  const durationInSeconds = await input.computeDuration();
+  return durationInSeconds;
+};
+```
+
+## Usage
+
+```tsx
+const duration = await getVideoDuration("https://remotion.media/video.mp4");
+console.log(duration); // e.g. 10.5 (seconds)
+```
+
+## Video files from the public/ directory
+
+Make sure to wrap the file path in `staticFile()`:
+
+```tsx
+import { staticFile } from "remotion";
+
+const duration = await getVideoDuration(staticFile("video.mp4"));
+```
+
+## In Node.js and Bun
+
+Use `FileSource` instead of `UrlSource`:
+
+```tsx
+import { Input, ALL_FORMATS, FileSource } from "mediabunny";
+
+const input = new Input({
+  formats: ALL_FORMATS,
+  source: new FileSource(file), // File object from input or drag-drop
+});
+
+const durationInSeconds = await input.computeDuration();
+```

.agents/skills/remotion-best-practices/rules/gifs.md

@@ -0,0 +1,141 @@
+---
+name: gif
+description: Displaying GIFs, APNG, AVIF and WebP in Remotion
+metadata:
+  tags: gif, animation, images, animated, apng, avif, webp
+---
+
+# Using Animated images in Remotion
+
+## Basic usage
+
+Use `<AnimatedImage>` to display a GIF, APNG, AVIF or WebP image synchronized with Remotion's timeline:
+
+```tsx
+import { AnimatedImage, staticFile } from "remotion";
+
+export const MyComposition = () => {
+  return (
+    <AnimatedImage src={staticFile("animation.gif")} width={500} height={500} />
+  );
+};
+```
+
+Remote URLs are also supported (must have CORS enabled):
+
+```tsx
+<AnimatedImage
+  src="https://example.com/animation.gif"
+  width={500}
+  height={500}
+/>
+```
+
+## Sizing and fit
+
+Control how the image fills its container with the `fit` prop:
+
+```tsx
+// Stretch to fill (default)
+<AnimatedImage src={staticFile("animation.gif")} width={500} height={300} fit="fill" />
+
+// Maintain aspect ratio, fit inside container
+<AnimatedImage src={staticFile("animation.gif")} width={500} height={300} fit="contain" />
+
+// Fill container, crop if needed
+<AnimatedImage src={staticFile("animation.gif")} width={500} height={300} fit="cover" />
+```
+
+## Playback speed
+
+Use `playbackRate` to control the animation speed:
+
+```tsx
+<AnimatedImage src={staticFile("animation.gif")} width={500} height={500} playbackRate={2} /> {/* 2x speed */}
+<AnimatedImage src={staticFile("animation.gif")} width={500} height={500} playbackRate={0.5} /> {/* Half speed */}
+```
+
+## Looping behavior
+
+Control what happens when the animation finishes:
+
+```tsx
+// Loop indefinitely (default)
+<AnimatedImage src={staticFile("animation.gif")} width={500} height={500} loopBehavior="loop" />
+
+// Play once, show final frame
+<AnimatedImage src={staticFile("animation.gif")} width={500} height={500} loopBehavior="pause-after-finish" />
+
+// Play once, then clear canvas
+<AnimatedImage src={staticFile("animation.gif")} width={500} height={500} loopBehavior="clear-after-finish" />
+```
+
+## Styling
+
+Use the `style` prop for additional CSS (use `width` and `height` props for sizing):
+
+```tsx
+<AnimatedImage
+  src={staticFile("animation.gif")}
+  width={500}
+  height={500}
+  style={{
+    borderRadius: 20,
+    position: "absolute",
+    top: 100,
+    left: 50,
+  }}
+/>
+```
+
+## Getting GIF duration
+
+Use `getGifDurationInSeconds()` from `@remotion/gif` to get the duration of a GIF.
+
+```bash
+npx remotion add @remotion/gif
+```
+
+```tsx
+import { getGifDurationInSeconds } from "@remotion/gif";
+import { staticFile } from "remotion";
+
+const duration = await getGifDurationInSeconds(staticFile("animation.gif"));
+console.log(duration); // e.g. 2.5
+```
+
+This is useful for setting the composition duration to match the GIF:
+
+```tsx
+import { getGifDurationInSeconds } from "@remotion/gif";
+import { staticFile, CalculateMetadataFunction } from "remotion";
+
+const calculateMetadata: CalculateMetadataFunction = async () => {
+  const duration = await getGifDurationInSeconds(staticFile("animation.gif"));
+  return {
+    durationInFrames: Math.ceil(duration * 30),
+  };
+};
+```
+
+## Alternative
+
+If `<AnimatedImage>` does not work (only supported in Chrome and Firefox), you can use `<Gif>` from `@remotion/gif` instead.
+
+```bash
+npx remotion add @remotion/gif # If project uses npm
+bunx remotion add @remotion/gif # If project uses bun
+yarn remotion add @remotion/gif # If project uses yarn
+pnpm exec remotion add @remotion/gif # If project uses pnpm
+```
+
+```tsx
+import { Gif } from "@remotion/gif";
+import { staticFile } from "remotion";
+
+export const MyComposition = () => {
+  return <Gif src={staticFile("animation.gif")} width={500} height={500} />;
+};
+```
+
+The `<Gif>` component has the same props as `<AnimatedImage>` but only supports GIF files.

.agents/skills/remotion-best-practices/rules/images.md

@@ -0,0 +1,134 @@
+---
+name: images
+description: Embedding images in Remotion using the <Img> component
+metadata:
+  tags: images, img, staticFile, png, jpg, svg, webp
+---
+
+# Using images in Remotion
+
+## The `<Img>` component
+
+Always use the `<Img>` component from `remotion` to display images:
+
+```tsx
+import { Img, staticFile } from "remotion";
+
+export const MyComposition = () => {
+  return <Img src={staticFile("photo.png")} />;
+};
+```
+
+## Important restrictions
+
+**You MUST use the `<Img>` component from `remotion`.** Do not use:
+
+- Native HTML `<img>` elements
+- Next.js `<Image>` component
+- CSS `background-image`
+
+The `<Img>` component ensures images are fully loaded before rendering, preventing flickering and blank frames during video export.
+
+## Local images with staticFile()
+
+Place images in the `public/` folder and use `staticFile()` to reference them:
+
+```
+my-video/
+├─ public/
+│  ├─ logo.png
+│  ├─ avatar.jpg
+│  └─ icon.svg
+├─ src/
+├─ package.json
+```
+
+```tsx
+import { Img, staticFile } from "remotion";
+
+<Img src={staticFile("logo.png")} />;
+```
+
+## Remote images
+
+Remote URLs can be used directly without `staticFile()`:
+
+```tsx
+<Img src="https://example.com/image.png" />
+```
+
+Ensure remote images have CORS enabled.
+
+For animated GIFs, use the `<Gif>` component from `@remotion/gif` instead.
+
+## Sizing and positioning
+
+Use the `style` prop to control size and position:
+
+```tsx
+<Img
+  src={staticFile("photo.png")}
+  style={{
+    width: 500,
+    height: 300,
+    position: "absolute",
+    top: 100,
+    left: 50,
+    objectFit: "cover",
+  }}
+/>
+```
+
+## Dynamic image paths
+
+Use template literals for dynamic file references:
+
+```tsx
+import { Img, staticFile, useCurrentFrame } from "remotion";
+
+const frame = useCurrentFrame();
+
+// Image sequence
+<Img src={staticFile(`frames/frame${frame}.png`)} />
+
+// Selecting based on props
+<Img src={staticFile(`avatars/${props.userId}.png`)} />
+
+// Conditional images
+<Img src={staticFile(`icons/${isActive ? "active" : "inactive"}.svg`)} />
+```
+
+This pattern is useful for:
+
+- Image sequences (frame-by-frame animations)
+- User-specific avatars or profile images
+- Theme-based icons
+- State-dependent graphics
+
+## Getting image dimensions
+
+Use `getImageDimensions()` to get the dimensions of an image:
+
+```tsx
+import { getImageDimensions, staticFile } from "remotion";
+
+const { width, height } = await getImageDimensions(staticFile("photo.png"));
+```
+
+This is useful for calculating aspect ratios or sizing compositions:
+
+```tsx
+import {
+  getImageDimensions,
+  staticFile,
+  CalculateMetadataFunction,
+} from "remotion";
+
+const calculateMetadata: CalculateMetadataFunction = async () => {
+  const { width, height } = await getImageDimensions(staticFile("photo.png"));
+  return {
+    width,
+    height,
+  };
+};
+```

.agents/skills/remotion-best-practices/rules/import-srt-captions.md

@@ -0,0 +1,69 @@
+---
+name: import-srt-captions
+description: Importing .srt subtitle files into Remotion using @remotion/captions
+metadata:
+  tags: captions, subtitles, srt, import, parse
+---
+
+# Importing .srt subtitles into Remotion
+
+If you have an existing `.srt` subtitle file, you can import it into Remotion using `parseSrt()` from `@remotion/captions`.
+
+If you don't have a .srt file, read [Transcribing audio](transcribe-captions.md) for how to generate captions instead.
+
+## Prerequisites
+
+First, the @remotion/captions package needs to be installed.
+If it is not installed, use the following command:
+
+```bash
+npx remotion add @remotion/captions # If project uses npm
+bunx remotion add @remotion/captions # If project uses bun
+yarn remotion add @remotion/captions # If project uses yarn
+pnpm exec remotion add @remotion/captions # If project uses pnpm
+```
+
+## Reading an .srt file
+
+Use `staticFile()` to reference an `.srt` file in your `public` folder, then fetch and parse it:
+
+```tsx
+import { useState, useEffect, useCallback } from "react";
+import { AbsoluteFill, staticFile, useDelayRender } from "remotion";
+import { parseSrt } from "@remotion/captions";
+import type { Caption } from "@remotion/captions";
+
+export const MyComponent: React.FC = () => {
+  const [captions, setCaptions] = useState<Caption[] | null>(null);
+  const { delayRender, continueRender, cancelRender } = useDelayRender();
+  const [handle] = useState(() => delayRender());
+
+  const fetchCaptions = useCallback(async () => {
+    try {
+      const response = await fetch(staticFile("subtitles.srt"));
+      const text = await response.text();
+      const { captions: parsed } = parseSrt({ input: text });
+      setCaptions(parsed);
+      continueRender(handle);
+    } catch (e) {
+      cancelRender(e);
+    }
+  }, [continueRender, cancelRender, handle]);
+
+  useEffect(() => {
+    fetchCaptions();
+  }, [fetchCaptions]);
+
+  if (!captions) {
+    return null;
+  }
+
+  return <AbsoluteFill>{/* Use captions here */}</AbsoluteFill>;
+};
+```
+
+Remote URLs are also supported - you can `fetch()` a remote file via URL instead of using `staticFile()`.
+
+## Using imported captions
+
+Once parsed, the captions are in the `Caption` format and can be used with all `@remotion/captions` utilities.

.agents/skills/remotion-best-practices/rules/light-leaks.md

@@ -0,0 +1,73 @@
+---
+name: light-leaks
+description: Light leak overlay effects for Remotion using @remotion/light-leaks.
+metadata:
+  tags: light-leaks, overlays, effects, transitions
+---
+
+## Light Leaks
+
+This only works from Remotion 4.0.415 and up. Use `npx remotion versions` to check your Remotion version and `npx remotion upgrade` to upgrade your Remotion version.
+
+`<LightLeak>` from `@remotion/light-leaks` renders a WebGL-based light leak effect. It reveals during the first half of its duration and retracts during the second half.
+
+Typically used inside a `<TransitionSeries.Overlay>` to play over the cut point between two scenes. See the **transitions** rule for `<TransitionSeries>` and overlay usage.
+
+## Prerequisites
+
+```bash
+npx remotion add @remotion/light-leaks
+```
+
+## Basic usage with TransitionSeries
+
+```tsx
+import { TransitionSeries } from "@remotion/transitions";
+import { LightLeak } from "@remotion/light-leaks";
+
+<TransitionSeries>
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneA />
+  </TransitionSeries.Sequence>
+  <TransitionSeries.Overlay durationInFrames={30}>
+    <LightLeak />
+  </TransitionSeries.Overlay>
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneB />
+  </TransitionSeries.Sequence>
+</TransitionSeries>;
+```
+
+## Props
+
+- `durationInFrames?` — defaults to the parent sequence/composition duration. The effect reveals during the first half and retracts during the second half.
+- `seed?` — determines the shape of the light leak pattern. Different seeds produce different patterns. Default: `0`.
+- `hueShift?` — rotates the hue in degrees (`0`–`360`). Default: `0` (yellow-to-orange). `120` = green, `240` = blue.
+
+## Customizing the look
+
+```tsx
+import { LightLeak } from "@remotion/light-leaks";
+
+// Blue-tinted light leak with a different pattern
+<LightLeak seed={5} hueShift={240} />;
+
+// Green-tinted light leak
+<LightLeak seed={2} hueShift={120} />;
+```
+
+## Standalone usage
+
+`<LightLeak>` can also be used outside of `<TransitionSeries>`, for example as a decorative overlay in any composition:
+
+```tsx
+import { AbsoluteFill } from "remotion";
+import { LightLeak } from "@remotion/light-leaks";
+
+const MyComp: React.FC = () => (
+  <AbsoluteFill>
+    <MyContent />
+    <LightLeak durationInFrames={60} seed={3} />
+  </AbsoluteFill>
+);
+```

.agents/skills/remotion-best-practices/rules/lottie.md

@@ -0,0 +1,70 @@
+---
+name: lottie
+description: Embedding Lottie animations in Remotion.
+metadata:
+  category: Animation
+---
+
+# Using Lottie Animations in Remotion
+
+## Prerequisites
+
+First, the @remotion/lottie package needs to be installed.  
+If it is not, use the following command:
+
+```bash
+npx remotion add @remotion/lottie # If project uses npm
+bunx remotion add @remotion/lottie # If project uses bun
+yarn remotion add @remotion/lottie # If project uses yarn
+pnpm exec remotion add @remotion/lottie # If project uses pnpm
+```
+
+## Displaying a Lottie file
+
+To import a Lottie animation:
+
+- Fetch the Lottie asset
+- Wrap the loading process in `delayRender()` and `continueRender()`
+- Save the animation data in a state
+- Render the Lottie animation using the `Lottie` component from the `@remotion/lottie` package
+
+```tsx
+import { Lottie, LottieAnimationData } from "@remotion/lottie";
+import { useEffect, useState } from "react";
+import { cancelRender, continueRender, delayRender } from "remotion";
+
+export const MyAnimation = () => {
+  const [handle] = useState(() => delayRender("Loading Lottie animation"));
+
+  const [animationData, setAnimationData] =
+    useState<LottieAnimationData | null>(null);
+
+  useEffect(() => {
+    fetch("https://assets4.lottiefiles.com/packages/lf20_zyquagfl.json")
+      .then((data) => data.json())
+      .then((json) => {
+        setAnimationData(json);
+        continueRender(handle);
+      })
+      .catch((err) => {
+        cancelRender(err);
+      });
+  }, [handle]);
+
+  if (!animationData) {
+    return null;
+  }
+
+  return <Lottie animationData={animationData} />;
+};
+```
+
+## Styling and animating
+
+Lottie supports the `style` prop to allow styles and animations:
+
+```tsx
+return (
+  <Lottie animationData={animationData} style={{ width: 400, height: 400 }} />
+);
+```

.agents/skills/remotion-best-practices/rules/maps.md

@@ -0,0 +1,412 @@
+---
+name: maps
+description: Make map animations with Mapbox
+metadata:
+  tags: map, map animation, mapbox
+---
+
+Maps can be added to a Remotion video with Mapbox.  
+The [Mapbox documentation](https://docs.mapbox.com/mapbox-gl-js/api/) has the API reference.
+
+## Prerequisites
+
+Mapbox and `@turf/turf` need to be installed.
+
+Search the project for lockfiles and run the correct command depending on the package manager:
+
+If `package-lock.json` is found, use the following command:
+
+```bash
+npm i mapbox-gl @turf/turf @types/mapbox-gl
+```
+
+If `bun.lock` is found, use the following command:
+
+```bash
+bun i mapbox-gl @turf/turf @types/mapbox-gl
+```
+
+If `yarn.lock` is found, use the following command:
+
+```bash
+yarn add mapbox-gl @turf/turf @types/mapbox-gl
+```
+
+If `pnpm-lock.yaml` is found, use the following command:
+
+```bash
+pnpm i mapbox-gl @turf/turf @types/mapbox-gl
+```
+
+The user needs to create a free Mapbox account and create an access token by visiting https://console.mapbox.com/account/access-tokens/.
+
+The mapbox token needs to be added to the `.env` file:
+
+```txt title=".env"
+REMOTION_MAPBOX_TOKEN==pk.your-mapbox-access-token
+```
+
+## Adding a map
+
+Here is a basic example of a map in Remotion.
+
+```tsx
+import { useEffect, useMemo, useRef, useState } from "react";
+import { AbsoluteFill, useDelayRender, useVideoConfig } from "remotion";
+import mapboxgl, { Map } from "mapbox-gl";
+
+export const lineCoordinates = [
+  [6.56158447265625, 46.059891147620725],
+  [6.5691375732421875, 46.05679376154153],
+  [6.5842437744140625, 46.05059898938315],
+  [6.594886779785156, 46.04702502069337],
+  [6.601066589355469, 46.0460718554722],
+  [6.6089630126953125, 46.0365370783104],
+  [6.6185760498046875, 46.018420689207964],
+];
+
+mapboxgl.accessToken = process.env.REMOTION_MAPBOX_TOKEN as string;
+
+export const MyComposition = () => {
+  const ref = useRef<HTMLDivElement>(null);
+  const { delayRender, continueRender } = useDelayRender();
+
+  const { width, height } = useVideoConfig();
+  const [handle] = useState(() => delayRender("Loading map..."));
+  const [map, setMap] = useState<Map | null>(null);
+
+  useEffect(() => {
+    const _map = new Map({
+      container: ref.current!,
+      zoom: 11.53,
+      center: [6.5615, 46.0598],
+      pitch: 65,
+      bearing: 0,
+      style: "⁠mapbox://styles/mapbox/standard",
+      interactive: false,
+      fadeDuration: 0,
+    });
+
+    _map.on("style.load", () => {
+      // Hide all features from the Mapbox Standard style
+      const hideFeatures = [
+        "showRoadsAndTransit",
+        "showRoads",
+        "showTransit",
+        "showPedestrianRoads",
+        "showRoadLabels",
+        "showTransitLabels",
+        "showPlaceLabels",
+        "showPointOfInterestLabels",
+        "showPointsOfInterest",
+        "showAdminBoundaries",
+        "showLandmarkIcons",
+        "showLandmarkIconLabels",
+        "show3dObjects",
+        "show3dBuildings",
+        "show3dTrees",
+        "show3dLandmarks",
+        "show3dFacades",
+      ];
+      for (const feature of hideFeatures) {
+        _map.setConfigProperty("basemap", feature, false);
+      }
+
+      _map.setConfigProperty("basemap", "colorTrunks", "rgba(0, 0, 0, 0)");
+
+      _map.addSource("trace", {
+        type: "geojson",
+        data: {
+          type: "Feature",
+          properties: {},
+          geometry: {
+            type: "LineString",
+            coordinates: lineCoordinates,
+          },
+        },
+      });
+      _map.addLayer({
+        type: "line",
+        source: "trace",
+        id: "line",
+        paint: {
+          "line-color": "black",
+          "line-width": 5,
+        },
+        layout: {
+          "line-cap": "round",
+          "line-join": "round",
+        },
+      });
+    });
+
+    _map.on("load", () => {
+      continueRender(handle);
+      setMap(_map);
+    });
+  }, [handle, lineCoordinates]);
+
+  const style: React.CSSProperties = useMemo(
+    () => ({ width, height, position: "absolute" }),
+    [width, height],
+  );
+
+  return <AbsoluteFill ref={ref} style={style} />;
+};
+```
+
+The following is important in Remotion:
+
+- Animations must be driven by `useCurrentFrame()` and animations that Mapbox brings itself should be disabled. For example, the `fadeDuration` prop should be set to `0`, `interactive` should be set to `false`, etc.
+- Loading the map should be delayed using `useDelayRender()` and the map should be set to `null` until it is loaded.
+- The element containing the ref MUST have an explicit width and height and `position: "absolute"`.
+- Do not add a `_map.remove();` cleanup function.
+
+## Drawing lines
+
+Unless I request it, do not add a glow effect to the lines.
+Unless I request it, do not add additional points to the lines.
+
+## Map style
+
+By default, use the `mapbox://styles/mapbox/standard` style.  
+Hide the labels from the base map style.
+
+Unless I request otherwise, remove all features from the Mapbox Standard style.
+
+```tsx
+// Hide all features from the Mapbox Standard style
+const hideFeatures = [
+  "showRoadsAndTransit",
+  "showRoads",
+  "showTransit",
+  "showPedestrianRoads",
+  "showRoadLabels",
+  "showTransitLabels",
+  "showPlaceLabels",
+  "showPointOfInterestLabels",
+  "showPointsOfInterest",
+  "showAdminBoundaries",
+  "showLandmarkIcons",
+  "showLandmarkIconLabels",
+  "show3dObjects",
+  "show3dBuildings",
+  "show3dTrees",
+  "show3dLandmarks",
+  "show3dFacades",
+];
+for (const feature of hideFeatures) {
+  _map.setConfigProperty("basemap", feature, false);
+}
+
+_map.setConfigProperty("basemap", "colorMotorways", "transparent");
+_map.setConfigProperty("basemap", "colorRoads", "transparent");
+_map.setConfigProperty("basemap", "colorTrunks", "transparent");
+```
+
+## Animating the camera
+
+You can animate the camera along the line by adding a `useEffect` hook that updates the camera position based on the current frame.
+
+Unless I ask for it, do not jump between camera angles.
+
+```tsx
+import * as turf from "@turf/turf";
+import { interpolate } from "remotion";
+import { Easing } from "remotion";
+import { useCurrentFrame, useVideoConfig, useDelayRender } from "remotion";
+
+const animationDuration = 20;
+const cameraAltitude = 4000;
+```
+
+```tsx
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+const { delayRender, continueRender } = useDelayRender();
+
+useEffect(() => {
+  if (!map) {
+    return;
+  }
+  const handle = delayRender("Moving point...");
+
+  const routeDistance = turf.length(turf.lineString(lineCoordinates));
+
+  const progress = interpolate(
+    frame / fps,
+    [0.00001, animationDuration],
+    [0, 1],
+    {
+      easing: Easing.inOut(Easing.sin),
+      extrapolateLeft: "clamp",
+      extrapolateRight: "clamp",
+    },
+  );
+
+  const camera = map.getFreeCameraOptions();
+
+  const alongRoute = turf.along(
+    turf.lineString(lineCoordinates),
+    routeDistance * progress,
+  ).geometry.coordinates;
+
+  camera.lookAtPoint({
+    lng: alongRoute[0],
+    lat: alongRoute[1],
+  });
+
+  map.setFreeCameraOptions(camera);
+  map.once("idle", () => continueRender(handle));
+}, [lineCoordinates, fps, frame, handle, map]);
+```
+
+Notes:
+
+IMPORTANT: Keep the camera by default so north is up.
+IMPORTANT: For multi-step animations, set all properties at all stages (zoom, position, line progress) to prevent jumps. Override initial values.
+
+- The progress is clamped to a minimum value to avoid the line being empty, which can lead to turf errors
+- See [Timing](./timing.md) for more options for timing.
+- Consider the dimensions of the composition and make the lines thick enough and the label font size large enough to be legible for when the composition is scaled down.
+
+## Animating lines
+
+### Straight lines (linear interpolation)
+
+To animate a line that appears straight on the map, use linear interpolation between coordinates. Do NOT use turf's `lineSliceAlong` or `along` functions, as they use geodesic (great circle) calculations which appear curved on a Mercator projection.
+
+```tsx
+const frame = useCurrentFrame();
+const { durationInFrames } = useVideoConfig();
+
+useEffect(() => {
+  if (!map) return;
+
+  const animationHandle = delayRender("Animating line...");
+
+  const progress = interpolate(frame, [0, durationInFrames - 1], [0, 1], {
+    extrapolateLeft: "clamp",
+    extrapolateRight: "clamp",
+    easing: Easing.inOut(Easing.cubic),
+  });
+
+  // Linear interpolation for a straight line on the map
+  const start = lineCoordinates[0];
+  const end = lineCoordinates[1];
+  const currentLng = start[0] + (end[0] - start[0]) * progress;
+  const currentLat = start[1] + (end[1] - start[1]) * progress;
+
+  const lineData: GeoJSON.Feature<GeoJSON.LineString> = {
+    type: "Feature",
+    properties: {},
+    geometry: {
+      type: "LineString",
+      coordinates: [start, [currentLng, currentLat]],
+    },
+  };
+
+  const source = map.getSource("trace") as mapboxgl.GeoJSONSource;
+  if (source) {
+    source.setData(lineData);
+  }
+
+  map.once("idle", () => continueRender(animationHandle));
+}, [frame, map, durationInFrames]);
+```
+
+### Curved lines (geodesic/great circle)
+
+To animate a line that follows the geodesic (great circle) path between two points, use turf's `lineSliceAlong`. This is useful for showing flight paths or the actual shortest distance on Earth.
+
+```tsx
+import * as turf from "@turf/turf";
+
+const routeLine = turf.lineString(lineCoordinates);
+const routeDistance = turf.length(routeLine);
+
+const currentDistance = Math.max(0.001, routeDistance * progress);
+const slicedLine = turf.lineSliceAlong(routeLine, 0, currentDistance);
+
+const source = map.getSource("route") as mapboxgl.GeoJSONSource;
+if (source) {
+  source.setData(slicedLine);
+}
+```
+
+## Markers
+
+Add labels, and markers where appropriate.
+
+```tsx
+_map.addSource("markers", {
+  type: "geojson",
+  data: {
+    type: "FeatureCollection",
+    features: [
+      {
+        type: "Feature",
+        properties: { name: "Point 1" },
+        geometry: { type: "Point", coordinates: [-118.2437, 34.0522] },
+      },
+    ],
+  },
+});
+
+_map.addLayer({
+  id: "city-markers",
+  type: "circle",
+  source: "markers",
+  paint: {
+    "circle-radius": 40,
+    "circle-color": "#FF4444",
+    "circle-stroke-width": 4,
+    "circle-stroke-color": "#FFFFFF",
+  },
+});
+
+_map.addLayer({
+  id: "labels",
+  type: "symbol",
+  source: "markers",
+  layout: {
+    "text-field": ["get", "name"],
+    "text-font": ["DIN Pro Bold", "Arial Unicode MS Bold"],
+    "text-size": 50,
+    "text-offset": [0, 0.5],
+    "text-anchor": "top",
+  },
+  paint: {
+    "text-color": "#FFFFFF",
+    "text-halo-color": "#000000",
+    "text-halo-width": 2,
+  },
+});
+```
+
+Make sure they are big enough. Check the composition dimensions and scale the labels accordingly.
+For a composition size of 1920x1080, the label font size should be at least 40px.
+
+IMPORTANT: Keep the `text-offset` small enough so it is close to the marker. Consider the marker circle radius. For a circle radius of 40, this is a good offset:
+
+```tsx
+"text-offset": [0, 0.5],
+```
+
+## 3D buildings
+
+To enable 3D buildings, use the following code:
+
+```tsx
+_map.setConfigProperty("basemap", "show3dObjects", true);
+_map.setConfigProperty("basemap", "show3dLandmarks", true);
+_map.setConfigProperty("basemap", "show3dBuildings", true);
+```
+
+## Rendering
+
+When rendering a map animation, make sure to render with the following flags:
+
+```
+npx remotion render --gl=angle --concurrency=1
+```

.agents/skills/remotion-best-practices/rules/measuring-dom-nodes.md

@@ -0,0 +1,34 @@
+---
+name: measuring-dom-nodes
+description: Measuring DOM element dimensions in Remotion
+metadata:
+  tags: measure, layout, dimensions, getBoundingClientRect, scale
+---
+
+# Measuring DOM nodes in Remotion
+
+Remotion applies a `scale()` transform to the video container, which affects values from `getBoundingClientRect()`. Use `useCurrentScale()` to get correct measurements.
+
+## Measuring element dimensions
+
+```tsx
+import { useCurrentScale } from "remotion";
+import { useRef, useEffect, useState } from "react";
+
+export const MyComponent = () => {
+  const ref = useRef<HTMLDivElement>(null);
+  const scale = useCurrentScale();
+  const [dimensions, setDimensions] = useState({ width: 0, height: 0 });
+
+  useEffect(() => {
+    if (!ref.current) return;
+    const rect = ref.current.getBoundingClientRect();
+    setDimensions({
+      width: rect.width / scale,
+      height: rect.height / scale,
+    });
+  }, [scale]);
+
+  return <div ref={ref}>Content to measure</div>;
+};
+```

.agents/skills/remotion-best-practices/rules/measuring-text.md

@@ -0,0 +1,140 @@
+---
+name: measuring-text
+description: Measuring text dimensions, fitting text to containers, and checking overflow
+metadata:
+  tags: measure, text, layout, dimensions, fitText, fillTextBox
+---
+
+# Measuring text in Remotion
+
+## Prerequisites
+
+Install @remotion/layout-utils if it is not already installed:
+
+```bash
+npx remotion add @remotion/layout-utils
+```
+
+## Measuring text dimensions
+
+Use `measureText()` to calculate the width and height of text:
+
+```tsx
+import { measureText } from "@remotion/layout-utils";
+
+const { width, height } = measureText({
+  text: "Hello World",
+  fontFamily: "Arial",
+  fontSize: 32,
+  fontWeight: "bold",
+});
+```
+
+Results are cached - duplicate calls return the cached result.
+
+## Fitting text to a width
+
+Use `fitText()` to find the optimal font size for a container:
+
+```tsx
+import { fitText } from "@remotion/layout-utils";
+
+const { fontSize } = fitText({
+  text: "Hello World",
+  withinWidth: 600,
+  fontFamily: "Inter",
+  fontWeight: "bold",
+});
+
+return (
+  <div
+    style={{
+      fontSize: Math.min(fontSize, 80), // Cap at 80px
+      fontFamily: "Inter",
+      fontWeight: "bold",
+    }}
+  >
+    Hello World
+  </div>
+);
+```
+
+## Checking text overflow
+
+Use `fillTextBox()` to check if text exceeds a box:
+
+```tsx
+import { fillTextBox } from "@remotion/layout-utils";
+
+const box = fillTextBox({ maxBoxWidth: 400, maxLines: 3 });
+
+const words = ["Hello", "World", "This", "is", "a", "test"];
+for (const word of words) {
+  const { exceedsBox } = box.add({
+    text: word + " ",
+    fontFamily: "Arial",
+    fontSize: 24,
+  });
+  if (exceedsBox) {
+    // Text would overflow, handle accordingly
+    break;
+  }
+}
+```
+
+## Best practices
+
+**Load fonts first:** Only call measurement functions after fonts are loaded.
+
+```tsx
+import { loadFont } from "@remotion/google-fonts/Inter";
+
+const { fontFamily, waitUntilDone } = loadFont("normal", {
+  weights: ["400"],
+  subsets: ["latin"],
+});
+
+waitUntilDone().then(() => {
+  // Now safe to measure
+  const { width } = measureText({
+    text: "Hello",
+    fontFamily,
+    fontSize: 32,
+  });
+});
+```
+
+**Use validateFontIsLoaded:** Catch font loading issues early:
+
+```tsx
+measureText({
+  text: "Hello",
+  fontFamily: "MyCustomFont",
+  fontSize: 32,
+  validateFontIsLoaded: true, // Throws if font not loaded
+});
+```
+
+**Match font properties:** Use the same properties for measurement and rendering:
+
+```tsx
+const fontStyle = {
+  fontFamily: "Inter",
+  fontSize: 32,
+  fontWeight: "bold" as const,
+  letterSpacing: "0.5px",
+};
+
+const { width } = measureText({
+  text: "Hello",
+  ...fontStyle,
+});
+
+return <div style={fontStyle}>Hello</div>;
+```
+
+**Avoid padding and border:** Use `outline` instead of `border` to prevent layout differences:
+
+```tsx
+<div style={{ outline: "2px solid red" }}>Text</div>
+```

.agents/skills/remotion-best-practices/rules/parameters.md

@@ -0,0 +1,109 @@
+---
+name: parameters
+description: Make a video parametrizable by adding a Zod schema
+metadata:
+  tags: parameters, zod, schema
+---
+
+To make a video parametrizable, a Zod schema can be added to a composition.
+
+First, `zod` must be installed .
+
+Search the project for lockfiles and run the correct command depending on the package manager:
+
+If `package-lock.json` is found, use the following command:
+
+```bash
+npm i zod
+```
+
+If `bun.lockb` is found, use the following command:
+
+```bash
+bun i zod
+```
+
+If `yarn.lock` is found, use the following command:
+
+```bash
+yarn add zod
+```
+
+If `pnpm-lock.yaml` is found, use the following command:
+
+```bash
+pnpm i zod
+```
+
+Then, a Zod schema can be defined alongside the component:
+
+```tsx title="src/MyComposition.tsx"
+import { z } from "zod";
+
+export const MyCompositionSchema = z.object({
+  title: z.string(),
+});
+
+const MyComponent: React.FC<z.infer<typeof MyCompositionSchema>> = () => {
+  return (
+    <div>
+      <h1>{props.title}</h1>
+    </div>
+  );
+};
+```
+
+In the root file, the schema can be passed to the composition:
+
+```tsx title="src/Root.tsx"
+import { Composition } from "remotion";
+import { MycComponent, MyCompositionSchema } from "./MyComposition";
+
+export const RemotionRoot = () => {
+  return (
+    <Composition
+      id="MyComposition"
+      component={MyComponent}
+      durationInFrames={100}
+      fps={30}
+      width={1080}
+      height={1080}
+      defaultProps={{ title: "Hello World" }}
+      schema={MyCompositionSchema}
+    />
+  );
+};
+```
+
+Now, the user can edit the parameter visually in the sidebar.
+
+All schemas that are supported by Zod are supported by Remotion.
+
+Remotion requires that the top-level type is a z.object(), because the collection of props of a React component is always an object.
+
+## Color picker
+
+For adding a color picker, use `zColor()` from `@remotion/zod-types`.
+
+If it is not installed, use the following command:
+
+```bash
+npx remotion add @remotion/zod-types # If project uses npm
+bunx remotion add @remotion/zod-types # If project uses bun
+yarn remotion add @remotion/zod-types # If project uses yarn
+pnpm exec remotion add @remotion/zod-types # If project uses pnpm
+```
+
+Then import `zColor` from `@remotion/zod-types`:
+
+```tsx
+import { zColor } from "@remotion/zod-types";
+```
+
+Then use it in the schema:
+
+```tsx
+export const MyCompositionSchema = z.object({
+  color: zColor(),
+});
+```

.agents/skills/remotion-best-practices/rules/sequencing.md

@@ -0,0 +1,118 @@
+---
+name: sequencing
+description: Sequencing patterns for Remotion - delay, trim, limit duration of items
+metadata:
+  tags: sequence, series, timing, delay, trim
+---
+
+Use `<Sequence>` to delay when an element appears in the timeline.
+
+```tsx
+import { Sequence } from "remotion";
+
+const {fps} = useVideoConfig();
+
+<Sequence from={1 * fps} durationInFrames={2 * fps} premountFor={1 * fps}>
+  <Title />
+</Sequence>
+<Sequence from={2 * fps} durationInFrames={2 * fps} premountFor={1 * fps}>
+  <Subtitle />
+</Sequence>
+```
+
+This will by default wrap the component in an absolute fill element.  
+If the items should not be wrapped, use the `layout` prop:
+
+```tsx
+<Sequence layout="none">
+  <Title />
+</Sequence>
+```
+
+## Premounting
+
+This loads the component in the timeline before it is actually played.  
+Always premount any `<Sequence>`!
+
+```tsx
+<Sequence premountFor={1 * fps}>
+  <Title />
+</Sequence>
+```
+
+## Series
+
+Use `<Series>` when elements should play one after another without overlap.
+
+```tsx
+import { Series } from "remotion";
+
+<Series>
+  <Series.Sequence durationInFrames={45}>
+    <Intro />
+  </Series.Sequence>
+  <Series.Sequence durationInFrames={60}>
+    <MainContent />
+  </Series.Sequence>
+  <Series.Sequence durationInFrames={30}>
+    <Outro />
+  </Series.Sequence>
+</Series>;
+```
+
+Same as with `<Sequence>`, the items will be wrapped in an absolute fill element by default when using `<Series.Sequence>`, unless the `layout` prop is set to `none`.
+
+### Series with overlaps
+
+Use negative offset for overlapping sequences:
+
+```tsx
+<Series>
+  <Series.Sequence durationInFrames={60}>
+    <SceneA />
+  </Series.Sequence>
+  <Series.Sequence offset={-15} durationInFrames={60}>
+    {/* Starts 15 frames before SceneA ends */}
+    <SceneB />
+  </Series.Sequence>
+</Series>
+```
+
+## Frame References Inside Sequences
+
+Inside a Sequence, `useCurrentFrame()` returns the local frame (starting from 0):
+
+```tsx
+<Sequence from={60} durationInFrames={30}>
+  <MyComponent />
+  {/* Inside MyComponent, useCurrentFrame() returns 0-29, not 60-89 */}
+</Sequence>
+```
+
+## Nested Sequences
+
+Sequences can be nested for complex timing:
+
+```tsx
+<Sequence from={0} durationInFrames={120}>
+  <Background />
+  <Sequence from={15} durationInFrames={90} layout="none">
+    <Title />
+  </Sequence>
+  <Sequence from={45} durationInFrames={60} layout="none">
+    <Subtitle />
+  </Sequence>
+</Sequence>
+```
+
+## Nesting compositions within another
+
+To add a composition within another composition, you can use the `<Sequence>` component with a `width` and `height` prop to specify the size of the composition.
+
+```tsx
+<AbsoluteFill>
+  <Sequence width={COMPOSITION_WIDTH} height={COMPOSITION_HEIGHT}>
+    <CompositionComponent />
+  </Sequence>
+</AbsoluteFill>
+```

.agents/skills/remotion-best-practices/rules/sfx.md

@@ -0,0 +1,26 @@
+---
+name: sfx
+description: Including sound effects
+metadata:
+  tags: sfx, sound, effect, audio
+---
+
+To include a sound effect, use the `<Audio>` tag:
+
+```tsx
+import { Audio } from "@remotion/sfx";
+
+<Audio src={"https://remotion.media/whoosh.wav"} />;
+```
+
+The following sound effects are available:
+
+- `https://remotion.media/whoosh.wav`
+- `https://remotion.media/whip.wav`
+- `https://remotion.media/page-turn.wav`
+- `https://remotion.media/switch.wav`
+- `https://remotion.media/mouse-click.wav`
+- `https://remotion.media/shutter-modern.wav`
+- `https://remotion.media/shutter-old.wav`
+
+For more sound effects, search the internet. A good resource is https://github.com/kapishdima/soundcn/tree/main/assets.

.agents/skills/remotion-best-practices/rules/subtitles.md

@@ -0,0 +1,36 @@
+---
+name: subtitles
+description: subtitles and caption rules
+metadata:
+  tags: subtitles, captions, remotion, json
+---
+
+All captions must be processed in JSON. The captions must use the `Caption` type which is the following:
+
+```ts
+import type { Caption } from "@remotion/captions";
+```
+
+This is the definition:
+
+```ts
+type Caption = {
+  text: string;
+  startMs: number;
+  endMs: number;
+  timestampMs: number | null;
+  confidence: number | null;
+};
+```
+
+## Generating captions
+
+To transcribe video and audio files to generate captions, load the [./transcribe-captions.md](./transcribe-captions.md) file for more instructions.
+
+## Displaying captions
+
+To display captions in your video, load the [./display-captions.md](./display-captions.md) file for more instructions.
+
+## Importing captions
+
+To import captions from a .srt file, load the [./import-srt-captions.md](./import-srt-captions.md) file for more instructions.

.agents/skills/remotion-best-practices/rules/tailwind.md

@@ -0,0 +1,11 @@
+---
+name: tailwind
+description: Using TailwindCSS in Remotion.
+metadata:
+---
+
+You can and should use TailwindCSS in Remotion, if TailwindCSS is installed in the project.
+
+Don't use `transition-*` or `animate-*` classes - always animate using the `useCurrentFrame()` hook.
+
+Tailwind must be installed and enabled first in a Remotion project - fetch https://www.remotion.dev/docs/tailwind using WebFetch for instructions.

.agents/skills/remotion-best-practices/rules/text-animations.md

@@ -0,0 +1,20 @@
+---
+name: text-animations
+description: Typography and text animation patterns for Remotion.
+metadata:
+  tags: typography, text, typewriter, highlighter ken
+---
+
+## Text animations
+
+Based on `useCurrentFrame()`, reduce the string character by character to create a typewriter effect.
+
+## Typewriter Effect
+
+See [Typewriter](assets/text-animations-typewriter.tsx) for an advanced example with a blinking cursor and a pause after the first sentence.
+
+Always use string slicing for typewriter effects. Never use per-character opacity.
+
+## Word Highlighting
+
+See [Word Highlight](assets/text-animations-word-highlight.tsx) for an example for how a word highlight is animated, like with a highlighter pen.

.agents/skills/remotion-best-practices/rules/timing.md

@@ -0,0 +1,179 @@
+---
+name: timing
+description: Interpolation curves in Remotion - linear, easing, spring animations
+metadata:
+  tags: spring, bounce, easing, interpolation
+---
+
+A simple linear interpolation is done using the `interpolate` function.
+
+```ts title="Going from 0 to 1 over 100 frames"
+import { interpolate } from "remotion";
+
+const opacity = interpolate(frame, [0, 100], [0, 1]);
+```
+
+By default, the values are not clamped, so the value can go outside the range [0, 1].  
+Here is how they can be clamped:
+
+```ts title="Going from 0 to 1 over 100 frames with extrapolation"
+const opacity = interpolate(frame, [0, 100], [0, 1], {
+  extrapolateRight: "clamp",
+  extrapolateLeft: "clamp",
+});
+```
+
+## Spring animations
+
+Spring animations have a more natural motion.  
+They go from 0 to 1 over time.
+
+```ts title="Spring animation from 0 to 1 over 100 frames"
+import { spring, useCurrentFrame, useVideoConfig } from "remotion";
+
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+const scale = spring({
+  frame,
+  fps,
+});
+```
+
+### Physical properties
+
+The default configuration is: `mass: 1, damping: 10, stiffness: 100`.  
+This leads to the animation having a bit of bounce before it settles.
+
+The config can be overwritten like this:
+
+```ts
+const scale = spring({
+  frame,
+  fps,
+  config: { damping: 200 },
+});
+```
+
+The recommended configuration for a natural motion without a bounce is: `{ damping: 200 }`.
+
+Here are some common configurations:
+
+```tsx
+const smooth = { damping: 200 }; // Smooth, no bounce (subtle reveals)
+const snappy = { damping: 20, stiffness: 200 }; // Snappy, minimal bounce (UI elements)
+const bouncy = { damping: 8 }; // Bouncy entrance (playful animations)
+const heavy = { damping: 15, stiffness: 80, mass: 2 }; // Heavy, slow, small bounce
+```
+
+### Delay
+
+The animation starts immediately by default.  
+Use the `delay` parameter to delay the animation by a number of frames.
+
+```tsx
+const entrance = spring({
+  frame: frame - ENTRANCE_DELAY,
+  fps,
+  delay: 20,
+});
+```
+
+### Duration
+
+A `spring()` has a natural duration based on the physical properties.  
+To stretch the animation to a specific duration, use the `durationInFrames` parameter.
+
+```tsx
+const spring = spring({
+  frame,
+  fps,
+  durationInFrames: 40,
+});
+```
+
+### Combining spring() with interpolate()
+
+Map spring output (0-1) to custom ranges:
+
+```tsx
+const springProgress = spring({
+  frame,
+  fps,
+});
+
+// Map to rotation
+const rotation = interpolate(springProgress, [0, 1], [0, 360]);
+
+<div style={{ rotate: rotation + "deg" }} />;
+```
+
+### Adding springs
+
+Springs return just numbers, so math can be performed:
+
+```tsx
+const frame = useCurrentFrame();
+const { fps, durationInFrames } = useVideoConfig();
+
+const inAnimation = spring({
+  frame,
+  fps,
+});
+const outAnimation = spring({
+  frame,
+  fps,
+  durationInFrames: 1 * fps,
+  delay: durationInFrames - 1 * fps,
+});
+
+const scale = inAnimation - outAnimation;
+```
+
+## Easing
+
+Easing can be added to the `interpolate` function:
+
+```ts
+import { interpolate, Easing } from "remotion";
+
+const value1 = interpolate(frame, [0, 100], [0, 1], {
+  easing: Easing.inOut(Easing.quad),
+  extrapolateLeft: "clamp",
+  extrapolateRight: "clamp",
+});
+```
+
+The default easing is `Easing.linear`.  
+There are various other convexities:
+
+- `Easing.in` for starting slow and accelerating
+- `Easing.out` for starting fast and slowing down
+- `Easing.inOut`
+
+and curves (sorted from most linear to most curved):
+
+- `Easing.quad`
+- `Easing.sin`
+- `Easing.exp`
+- `Easing.circle`
+
+Convexities and curves need be combined for an easing function:
+
+```ts
+const value1 = interpolate(frame, [0, 100], [0, 1], {
+  easing: Easing.inOut(Easing.quad),
+  extrapolateLeft: "clamp",
+  extrapolateRight: "clamp",
+});
+```
+
+Cubic bezier curves are also supported:
+
+```ts
+const value1 = interpolate(frame, [0, 100], [0, 1], {
+  easing: Easing.bezier(0.8, 0.22, 0.96, 0.65),
+  extrapolateLeft: "clamp",
+  extrapolateRight: "clamp",
+});
+```

.agents/skills/remotion-best-practices/rules/transcribe-captions.md

@@ -0,0 +1,70 @@
+---
+name: transcribe-captions
+description: Transcribing audio to generate captions in Remotion
+metadata:
+  tags: captions, transcribe, whisper, audio, speech-to-text
+---
+
+# Transcribing audio
+
+To transcribe audio to generate captions in Remotion, you can use the [`transcribe()`](https://www.remotion.dev/docs/install-whisper-cpp/transcribe) function from the [`@remotion/install-whisper-cpp`](https://www.remotion.dev/docs/install-whisper-cpp) package.
+
+## Prerequisites
+
+First, the @remotion/install-whisper-cpp package needs to be installed.
+If it is not installed, use the following command:
+
+```bash
+npx remotion add @remotion/install-whisper-cpp
+```
+
+## Transcribing
+
+Make a Node.js script to download Whisper.cpp and a model, and transcribe the audio.
+
+```ts
+import path from "path";
+import {
+  downloadWhisperModel,
+  installWhisperCpp,
+  transcribe,
+  toCaptions,
+} from "@remotion/install-whisper-cpp";
+import fs from "fs";
+
+const to = path.join(process.cwd(), "whisper.cpp");
+
+await installWhisperCpp({
+  to,
+  version: "1.5.5",
+});
+
+await downloadWhisperModel({
+  model: "medium.en",
+  folder: to,
+});
+
+// Convert the audio to a 16KHz wav file first if needed:
+// import {execSync} from 'child_process';
+// execSync('ffmpeg -i /path/to/audio.mp4 -ar 16000 /path/to/audio.wav -y');
+
+const whisperCppOutput = await transcribe({
+  model: "medium.en",
+  whisperPath: to,
+  whisperCppVersion: "1.5.5",
+  inputPath: "/path/to/audio123.wav",
+  tokenLevelTimestamps: true,
+});
+
+// Optional: Apply our recommended postprocessing
+const { captions } = toCaptions({
+  whisperCppOutput,
+});
+
+// Write it to the public/ folder so it can be fetched from Remotion
+fs.writeFileSync("captions123.json", JSON.stringify(captions, null, 2));
+```
+
+Transcribe each clip individually and create multiple JSON files.
+
+See [Displaying captions](display-captions.md) for how to display the captions in Remotion.

.agents/skills/remotion-best-practices/rules/transitions.md

@@ -0,0 +1,197 @@
+---
+name: transitions
+description: Scene transitions and overlays for Remotion using TransitionSeries.
+metadata:
+  tags: transitions, overlays, fade, slide, wipe, scenes
+---
+
+## TransitionSeries
+
+`<TransitionSeries>` arranges scenes and supports two ways to enhance the cut point between them:
+
+- **Transitions** (`<TransitionSeries.Transition>`) — crossfade, slide, wipe, etc. between two scenes. Shortens the timeline because both scenes play simultaneously during the transition.
+- **Overlays** (`<TransitionSeries.Overlay>`) — render an effect (e.g. a light leak) on top of the cut point without shortening the timeline.
+
+Children are absolutely positioned.
+
+## Prerequisites
+
+```bash
+npx remotion add @remotion/transitions
+```
+
+## Transition example
+
+```tsx
+import { TransitionSeries, linearTiming } from "@remotion/transitions";
+import { fade } from "@remotion/transitions/fade";
+
+<TransitionSeries>
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneA />
+  </TransitionSeries.Sequence>
+  <TransitionSeries.Transition
+    presentation={fade()}
+    timing={linearTiming({ durationInFrames: 15 })}
+  />
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneB />
+  </TransitionSeries.Sequence>
+</TransitionSeries>;
+```
+
+## Overlay example
+
+Any React component can be used as an overlay. For a ready-made effect, see the **light-leaks** rule.
+
+```tsx
+import { TransitionSeries } from "@remotion/transitions";
+import { LightLeak } from "@remotion/light-leaks";
+
+<TransitionSeries>
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneA />
+  </TransitionSeries.Sequence>
+  <TransitionSeries.Overlay durationInFrames={20}>
+    <LightLeak />
+  </TransitionSeries.Overlay>
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneB />
+  </TransitionSeries.Sequence>
+</TransitionSeries>;
+```
+
+## Mixing transitions and overlays
+
+Transitions and overlays can coexist in the same `<TransitionSeries>`, but an overlay cannot be adjacent to a transition or another overlay.
+
+```tsx
+import { TransitionSeries, linearTiming } from "@remotion/transitions";
+import { fade } from "@remotion/transitions/fade";
+import { LightLeak } from "@remotion/light-leaks";
+
+<TransitionSeries>
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneA />
+  </TransitionSeries.Sequence>
+  <TransitionSeries.Overlay durationInFrames={30}>
+    <LightLeak />
+  </TransitionSeries.Overlay>
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneB />
+  </TransitionSeries.Sequence>
+  <TransitionSeries.Transition
+    presentation={fade()}
+    timing={linearTiming({ durationInFrames: 15 })}
+  />
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneC />
+  </TransitionSeries.Sequence>
+</TransitionSeries>;
+```
+
+## Transition props
+
+`<TransitionSeries.Transition>` requires:
+
+- `presentation` — the visual effect (e.g. `fade()`, `slide()`, `wipe()`).
+- `timing` — controls speed and easing (e.g. `linearTiming()`, `springTiming()`).
+
+## Overlay props
+
+`<TransitionSeries.Overlay>` accepts:
+
+- `durationInFrames` — how long the overlay is visible (positive integer).
+- `offset?` — shifts the overlay relative to the cut point center. Positive = later, negative = earlier. Default: `0`.
+
+## Available transition types
+
+Import transitions from their respective modules:
+
+```tsx
+import { fade } from "@remotion/transitions/fade";
+import { slide } from "@remotion/transitions/slide";
+import { wipe } from "@remotion/transitions/wipe";
+import { flip } from "@remotion/transitions/flip";
+import { clockWipe } from "@remotion/transitions/clock-wipe";
+```
+
+## Slide transition with direction
+
+```tsx
+import { slide } from "@remotion/transitions/slide";
+
+<TransitionSeries.Transition
+  presentation={slide({ direction: "from-left" })}
+  timing={linearTiming({ durationInFrames: 20 })}
+/>;
+```
+
+Directions: `"from-left"`, `"from-right"`, `"from-top"`, `"from-bottom"`
+
+## Timing options
+
+```tsx
+import { linearTiming, springTiming } from "@remotion/transitions";
+
+// Linear timing - constant speed
+linearTiming({ durationInFrames: 20 });
+
+// Spring timing - organic motion
+springTiming({ config: { damping: 200 }, durationInFrames: 25 });
+```
+
+## Duration calculation
+
+Transitions overlap adjacent scenes, so the total composition length is **shorter** than the sum of all sequence durations. Overlays do **not** affect the total duration.
+
+For example, with two 60-frame sequences and a 15-frame transition:
+
+- Without transitions: `60 + 60 = 120` frames
+- With transition: `60 + 60 - 15 = 105` frames
+
+Adding an overlay between two other sequences does not change the total.
+
+### Getting the duration of a transition
+
+Use the `getDurationInFrames()` method on the timing object:
+
+```tsx
+import { linearTiming, springTiming } from "@remotion/transitions";
+
+const linearDuration = linearTiming({
+  durationInFrames: 20,
+}).getDurationInFrames({ fps: 30 });
+// Returns 20
+
+const springDuration = springTiming({
+  config: { damping: 200 },
+}).getDurationInFrames({ fps: 30 });
+// Returns calculated duration based on spring physics
+```
+
+For `springTiming` without an explicit `durationInFrames`, the duration depends on `fps` because it calculates when the spring animation settles.
+
+### Calculating total composition duration
+
+```tsx
+import { linearTiming } from "@remotion/transitions";
+
+const scene1Duration = 60;
+const scene2Duration = 60;
+const scene3Duration = 60;
+
+const timing1 = linearTiming({ durationInFrames: 15 });
+const timing2 = linearTiming({ durationInFrames: 20 });
+
+const transition1Duration = timing1.getDurationInFrames({ fps: 30 });
+const transition2Duration = timing2.getDurationInFrames({ fps: 30 });
+
+const totalDuration =
+  scene1Duration +
+  scene2Duration +
+  scene3Duration -
+  transition1Duration -
+  transition2Duration;
+// 60 + 60 + 60 - 15 - 20 = 145 frames
+```

.agents/skills/remotion-best-practices/rules/transparent-videos.md

@@ -0,0 +1,106 @@
+---
+name: transparent-videos
+description: Rendering transparent videos in Remotion
+metadata:
+  tags: transparent, alpha, codec, vp9, prores, webm
+---
+
+# Rendering Transparent Videos
+
+Remotion can render transparent videos in two ways: as a ProRes video or as a WebM video.
+
+## Transparent ProRes
+
+Ideal for when importing into video editing software.
+
+**CLI:**
+
+```bash
+npx remotion render --image-format=png --pixel-format=yuva444p10le --codec=prores --prores-profile=4444 MyComp out.mov
+```
+
+**Default in Studio** (restart Studio after changing):
+
+```ts
+// remotion.config.ts
+import { Config } from "@remotion/cli/config";
+
+Config.setVideoImageFormat("png");
+Config.setPixelFormat("yuva444p10le");
+Config.setCodec("prores");
+Config.setProResProfile("4444");
+```
+
+**Setting it as the default export settings for a composition** (using `calculateMetadata`):
+
+```tsx
+import { CalculateMetadataFunction } from "remotion";
+
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  return {
+    defaultCodec: "prores",
+    defaultVideoImageFormat: "png",
+    defaultPixelFormat: "yuva444p10le",
+    defaultProResProfile: "4444",
+  };
+};
+
+<Composition
+  id="my-video"
+  component={MyVideo}
+  durationInFrames={150}
+  fps={30}
+  width={1920}
+  height={1080}
+  calculateMetadata={calculateMetadata}
+/>;
+```
+
+## Transparent WebM (VP9)
+
+Ideal for when playing in a browser.
+
+**CLI:**
+
+```bash
+npx remotion render --image-format=png --pixel-format=yuva420p --codec=vp9 MyComp out.webm
+```
+
+**Default in Studio** (restart Studio after changing):
+
+```ts
+// remotion.config.ts
+import { Config } from "@remotion/cli/config";
+
+Config.setVideoImageFormat("png");
+Config.setPixelFormat("yuva420p");
+Config.setCodec("vp9");
+```
+
+**Setting it as the default export settings for a composition** (using `calculateMetadata`):
+
+```tsx
+import { CalculateMetadataFunction } from "remotion";
+
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  return {
+    defaultCodec: "vp8",
+    defaultVideoImageFormat: "png",
+    defaultPixelFormat: "yuva420p",
+  };
+};
+
+<Composition
+  id="my-video"
+  component={MyVideo}
+  durationInFrames={150}
+  fps={30}
+  width={1920}
+  height={1080}
+  calculateMetadata={calculateMetadata}
+/>;
+```

.agents/skills/remotion-best-practices/rules/trimming.md

@@ -0,0 +1,51 @@
+---
+name: trimming
+description: Trimming patterns for Remotion - cut the beginning or end of animations
+metadata:
+  tags: sequence, trim, clip, cut, offset
+---
+
+Use `<Sequence>` with a negative `from` value to trim the start of an animation.
+
+## Trim the Beginning
+
+A negative `from` value shifts time backwards, making the animation start partway through:
+
+```tsx
+import { Sequence, useVideoConfig } from "remotion";
+
+const fps = useVideoConfig();
+
+<Sequence from={-0.5 * fps}>
+  <MyAnimation />
+</Sequence>;
+```
+
+The animation appears 15 frames into its progress - the first 15 frames are trimmed off.
+Inside `<MyAnimation>`, `useCurrentFrame()` starts at 15 instead of 0.
+
+## Trim the End
+
+Use `durationInFrames` to unmount content after a specified duration:
+
+```tsx
+<Sequence durationInFrames={1.5 * fps}>
+  <MyAnimation />
+</Sequence>
+```
+
+The animation plays for 45 frames, then the component unmounts.
+
+## Trim and Delay
+
+Nest sequences to both trim the beginning and delay when it appears:
+
+```tsx
+<Sequence from={30}>
+  <Sequence from={-15}>
+    <MyAnimation />
+  </Sequence>
+</Sequence>
+```
+
+The inner sequence trims 15 frames from the start, and the outer sequence delays the result by 30 frames.

.agents/skills/remotion-best-practices/rules/videos.md

@@ -0,0 +1,171 @@
+---
+name: videos
+description: Embedding videos in Remotion - trimming, volume, speed, looping, pitch
+metadata:
+  tags: video, media, trim, volume, speed, loop, pitch
+---
+
+# Using videos in Remotion
+
+## Prerequisites
+
+First, the @remotion/media package needs to be installed.  
+If it is not, use the following command:
+
+```bash
+npx remotion add @remotion/media # If project uses npm
+bunx remotion add @remotion/media # If project uses bun
+yarn remotion add @remotion/media # If project uses yarn
+pnpm exec remotion add @remotion/media # If project uses pnpm
+```
+
+Use `<Video>` from `@remotion/media` to embed videos into your composition.
+
+```tsx
+import { Video } from "@remotion/media";
+import { staticFile } from "remotion";
+
+export const MyComposition = () => {
+  return <Video src={staticFile("video.mp4")} />;
+};
+```
+
+Remote URLs are also supported:
+
+```tsx
+<Video src="https://remotion.media/video.mp4" />
+```
+
+## Trimming
+
+Use `trimBefore` and `trimAfter` to remove portions of the video. Values are in seconds.
+
+```tsx
+const { fps } = useVideoConfig();
+
+return (
+  <Video
+    src={staticFile("video.mp4")}
+    trimBefore={2 * fps} // Skip the first 2 seconds
+    trimAfter={10 * fps} // End at the 10 second mark
+  />
+);
+```
+
+## Delaying
+
+Wrap the video in a `<Sequence>` to delay when it appears:
+
+```tsx
+import { Sequence, staticFile } from "remotion";
+import { Video } from "@remotion/media";
+
+const { fps } = useVideoConfig();
+
+return (
+  <Sequence from={1 * fps}>
+    <Video src={staticFile("video.mp4")} />
+  </Sequence>
+);
+```
+
+The video will appear after 1 second.
+
+## Sizing and Position
+
+Use the `style` prop to control size and position:
+
+```tsx
+<Video
+  src={staticFile("video.mp4")}
+  style={{
+    width: 500,
+    height: 300,
+    position: "absolute",
+    top: 100,
+    left: 50,
+    objectFit: "cover",
+  }}
+/>
+```
+
+## Volume
+
+Set a static volume (0 to 1):
+
+```tsx
+<Video src={staticFile("video.mp4")} volume={0.5} />
+```
+
+Or use a callback for dynamic volume based on the current frame:
+
+```tsx
+import { interpolate } from "remotion";
+
+const { fps } = useVideoConfig();
+
+return (
+  <Video
+    src={staticFile("video.mp4")}
+    volume={(f) =>
+      interpolate(f, [0, 1 * fps], [0, 1], { extrapolateRight: "clamp" })
+    }
+  />
+);
+```
+
+Use `muted` to silence the video entirely:
+
+```tsx
+<Video src={staticFile("video.mp4")} muted />
+```
+
+## Speed
+
+Use `playbackRate` to change the playback speed:
+
+```tsx
+<Video src={staticFile("video.mp4")} playbackRate={2} /> {/* 2x speed */}
+<Video src={staticFile("video.mp4")} playbackRate={0.5} /> {/* Half speed */}
+```
+
+Reverse playback is not supported.
+
+## Looping
+
+Use `loop` to loop the video indefinitely:
+
+```tsx
+<Video src={staticFile("video.mp4")} loop />
+```
+
+Use `loopVolumeCurveBehavior` to control how the frame count behaves when looping:
+
+- `"repeat"`: Frame count resets to 0 each loop (for `volume` callback)
+- `"extend"`: Frame count continues incrementing
+
+```tsx
+<Video
+  src={staticFile("video.mp4")}
+  loop
+  loopVolumeCurveBehavior="extend"
+  volume={(f) => interpolate(f, [0, 300], [1, 0])} // Fade out over multiple loops
+/>
+```
+
+## Pitch
+
+Use `toneFrequency` to adjust the pitch without affecting speed. Values range from 0.01 to 2:
+
+```tsx
+<Video
+  src={staticFile("video.mp4")}
+  toneFrequency={1.5} // Higher pitch
+/>
+<Video
+  src={staticFile("video.mp4")}
+  toneFrequency={0.8} // Lower pitch
+/>
+```
+
+Pitch shifting only works during server-side rendering, not in the Remotion Studio preview or in the `<Player />`.

.agents/skills/remotion-best-practices/rules/voiceover.md

@@ -0,0 +1,99 @@
+---
+name: voiceover
+description: Adding AI-generated voiceover to Remotion compositions using ElevenLabs TTS
+metadata:
+  tags: voiceover, audio, elevenlabs, tts, speech, calculateMetadata, dynamic duration
+---
+
+# Adding AI voiceover to a Remotion composition
+
+Use ElevenLabs TTS to generate speech audio per scene, then use [`calculateMetadata`](./calculate-metadata) to dynamically size the composition to match the audio.
+
+## Prerequisites
+
+An **ElevenLabs API key** is required (`ELEVENLABS_API_KEY` environment variable).
+
+**MUST** ask the user for their ElevenLabs API key if `ELEVENLABS_API_KEY` is not set. **MUST NOT** fall back to other TTS tools.
+
+Ensure the environment variable is available when running the generation script:
+
+```bash
+node --strip-types generate-voiceover.ts
+```
+
+## Generating audio with ElevenLabs
+
+Create a script that reads the config, calls the ElevenLabs API for each scene, and writes MP3 files to the `public/` directory so Remotion can access them via `staticFile()`.
+
+The core API call for a single scene:
+
+```ts title="generate-voiceover.ts"
+const response = await fetch(
+  `https://api.elevenlabs.io/v1/text-to-speech/${voiceId}`,
+  {
+    method: "POST",
+    headers: {
+      "xi-api-key": process.env.ELEVENLABS_API_KEY!,
+      "Content-Type": "application/json",
+      Accept: "audio/mpeg",
+    },
+    body: JSON.stringify({
+      text: "Welcome to the show.",
+      model_id: "eleven_multilingual_v2",
+      voice_settings: {
+        stability: 0.5,
+        similarity_boost: 0.75,
+        style: 0.3,
+      },
+    }),
+  },
+);
+
+const audioBuffer = Buffer.from(await response.arrayBuffer());
+writeFileSync(`public/voiceover/${compositionId}/${scene.id}.mp3`, audioBuffer);
+```
+
+## Dynamic composition duration with calculateMetadata
+
+Use [`calculateMetadata`](./calculate-metadata.md) to measure the [audio durations](./get-audio-duration.md) and set the composition length accordingly.
+
+```tsx
+import { CalculateMetadataFunction, staticFile } from "remotion";
+import { getAudioDuration } from "./get-audio-duration";
+
+const FPS = 30;
+
+const SCENE_AUDIO_FILES = [
+  "voiceover/my-comp/scene-01-intro.mp3",
+  "voiceover/my-comp/scene-02-main.mp3",
+  "voiceover/my-comp/scene-03-outro.mp3",
+];
+
+export const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  const durations = await Promise.all(
+    SCENE_AUDIO_FILES.map((file) => getAudioDuration(staticFile(file))),
+  );
+
+  const sceneDurations = durations.map((durationInSeconds) => {
+    return durationInSeconds * FPS;
+  });
+
+  return {
+    durationInFrames: Math.ceil(sceneDurations.reduce((sum, d) => sum + d, 0)),
+  };
+};
+```
+
+The computed `sceneDurations` are passed into the component via a `voiceover` prop so the component knows how long each scene should be.
+
+If the composition uses [`<TransitionSeries>`](./transitions.md), subtract the overlap from total duration: [./transitions.md#calculating-total-composition-duration](./transitions.md#calculating-total-composition-duration)
+
+## Rendering audio in the component
+
+See [audio.md](./audio.md) for more information on how to render audio in the component.
+
+## Delaying audio start
+
+See [audio.md#delaying](./audio.md#delaying) for more information on how to delay the audio start.

.github/workflows/release.yml

@@ -11,9 +11,6 @@ jobs:
   release:
     name: Release
     runs-on: ubuntu-latest
-    permissions:
-      contents: write
-      pull-requests: write
     steps:
       - name: Checkout repo
         uses: actions/checkout@v4
@@ -23,7 +20,6 @@ jobs:
         with:
           node-version: 20
           cache: npm
-          registry-url: https://registry.npmjs.org
 
       - name: Install dependencies
         run: npm ci
@@ -41,4 +37,4 @@ jobs:
           commit: "chore: version packages"
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -1,7 +1,3 @@
-# Claude Code local files
-.agents/
-skills-lock.json
-
 # Dependencies
 node_modules/
 

CHANGELOG.md

@@ -1,60 +1,4 @@
-# aicodeman
-
-## 0.2.9
-
-### Patch Changes
-
-- System-level performance optimizations (Phase 4): stream parent transcripts instead of full reads, consolidate subagent file watchers from 500 to ~50 using directory-level inotify, incremental state persistence with per-session JSON caching, and replace team watcher polling with chokidar fs events
-
-## 0.2.8
-
-### Patch Changes
-
-- Remove 159 lines of dead code: unused interfaces, functions, config constants, legacy no-op timer, and stale barrel re-exports
-
-## 0.2.7
-
-### Patch Changes
-
-- Fix race condition in StateStore where dirty flag was overwritten after async write, silently discarding mutations
-- Fix PlanOrchestrator session leak by adding session.stop() in finally blocks and centralizing cleanup
-- Fix symlink path traversal in file-content and file-raw endpoints by adding realpathSync validation
-- Fix PTY exit handler to clean up sessionListenerRefs, transcriptWatchers, runSummaryTrackers, and terminal batching state
-- Fix sendInput() fire-and-forget by propagating runPrompt errors to task queue via taskError event
-- Fix Ralph Loop tick() race condition by running checkTimeouts/assignTasks sequentially with per-iteration error handling
-- Fix shell injection in hook scripts by piping HOOK_DATA via printf to curl stdin instead of inline embedding
-- Narrow tail-file allowlist to remove ~/.cache and ~/.local/share paths that exposed credentials
-- Fix stored XSS in quick-start dropdown by escaping case names with escapeHtml()
-
-## 0.2.6
-
-### Patch Changes
-
-- Disable tunnel auto-start on boot; tunnel now only starts when user clicks the UI toggle
-
-## 0.2.5
-
-### Patch Changes
-
-- Fix 3 minor memory leaks: clear respawn timers in stop(), clean up persistDebounceTimers on session cleanup, reset \_parentNameCache on SSE reconnect
-
-## 0.2.4
-
-### Patch Changes
-
-- Fix tunnel button not working: settings PUT was rejected by strict Zod validation when sending full settings blob; now sends only `{tunnelEnabled}`. Added polling fallback for tunnel status in case SSE events are missed.
-
-## 0.2.3
-
-### Patch Changes
-
-- Fix tunnel button stuck on "Connecting..." when tunnel is already running on the server
-
-## 0.2.2
-
-### Patch Changes
-
-- Update CLAUDE.md app.js line count references
+# codeman
 
 ## 0.2.1
 

CLAUDE.md

@@ -8,8 +8,6 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 |------|---------|
 | Dev server | `npx tsx src/index.ts web` |
 | Type check | `tsc --noEmit` |
-| Lint | `npm run lint` (fix: `npm run lint:fix`) |
-| Format | `npm run format` (check: `npm run format:check`) |
 | Single test | `npx vitest run test/<file>.test.ts` |
 | Production | `npm run build && systemctl --user restart codeman-web` |
 
@@ -17,7 +15,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 **You may be running inside a Codeman-managed tmux session.** Before killing ANY tmux or Claude process:
 
-1. Check: `echo $CODEMAN_MUX` - if `1`, you're in a managed session
+1. Check: `echo $CODEMAN_TMUX` - if `1`, you're in a managed session
 2. **NEVER** run `tmux kill-session`, `pkill tmux`, or `pkill claude` without confirming
 3. Use the web UI or `./scripts/tmux-manager.sh` instead of direct kill commands
 
@@ -41,7 +39,7 @@ When user says "COM":
    ```bash
    cat > .changeset/$(openssl rand -hex 4).md << 'CHANGESET'
    ---
-   "aicodeman": patch
+   "codeman": patch
    ---
 
    Description of changes
@@ -52,7 +50,7 @@ When user says "COM":
 4. **Sync CLAUDE.md version**: Update the `**Version**` line below to match the new version from `package.json`
 5. **Commit and deploy**: `git add -A && git commit -m "chore: version packages" && git push && npm run build && systemctl --user restart codeman-web`
 
-**Version**: 0.2.9 (must match `package.json`)
+**Version**: 0.2.1 (must match `package.json`)
 
 ## Project Overview
 
@@ -79,29 +77,24 @@ npx tsx src/index.ts web           # Dev server (RECOMMENDED)
 npx tsx src/index.ts web --https   # With TLS (only needed for remote access)
 npm run typecheck                  # Type check
 tsc --noEmit --watch               # Continuous type checking
-npm run lint                       # ESLint
-npm run lint:fix                   # ESLint with auto-fix
-npm run format                     # Prettier format
-npm run format:check               # Prettier check only
 
-# Testing (see "Testing" section for CRITICAL safety warnings)
+# Testing (NEVER run full suite from inside Codeman — kills tmux sessions)
+# npx vitest run                   # ALL tests — DANGEROUS inside Codeman
 npx vitest run test/<file>.test.ts # Single file (SAFE)
 npx vitest run -t "pattern"        # Tests matching name
 npm run test:coverage              # With coverage report
 
 # Production
-npm run build                      # esbuild via scripts/build.mjs (not tsc)
-npm run start                      # node dist/index.js (production)
+npm run build
 systemctl --user restart codeman-web
 journalctl --user -u codeman-web -f
 ```
 
-**CI**: `.github/workflows/ci.yml` runs `typecheck`, `lint`, and `format:check` on push to master. Tests are intentionally excluded from CI (they spawn tmux).
-
 ## Common Gotchas
 
 - **Single-line prompts only** — `writeViaMux()` sends text and Enter separately; multi-line breaks Ink
-- **Don't kill tmux sessions blindly** — Check `$CODEMAN_MUX` first; you might be inside one
+- **Don't kill tmux sessions blindly** — Check `$CODEMAN_TMUX` first; you might be inside one
+- **Never run full test suite** — `npx vitest run` spawns/kills tmux sessions and will crash your Codeman session. Run individual test files only.
 - **Global regex `lastIndex` sharing** — `ANSI_ESCAPE_PATTERN_FULL/SIMPLE` have `g` flag; use `createAnsiPatternFull/Simple()` factory functions for fresh instances in loops
 - **DEC 2026 sync blocks** — Never discard incomplete sync blocks (START without END); buffer up to 50ms then flush. See `app.js:extractSyncSegments()`
 - **Terminal writes during buffer load** — Live SSE writes are queued while `_isLoadingBuffer` is true to prevent interleaving with historical data
@@ -119,7 +112,6 @@ journalctl --user -u codeman-web -f
 
 | File | Purpose |
 |------|---------|
-| `src/index.ts` | CLI entry point: global error recovery, uncaught exception guard, `MAX_CONSECUTIVE_ERRORS` auto-restart |
 | `src/session.ts` | PTY wrapper: `runPrompt()`, `startInteractive()`, `startShell()` |
 | `src/mux-interface.ts` | `TerminalMultiplexer` interface + `MuxSession` type |
 | `src/mux-factory.ts` | Create tmux multiplexer instance |
@@ -150,11 +142,10 @@ journalctl --user -u codeman-web -f
 | `src/prompts/index.ts` | Barrel export for all agent prompts |
 | `src/prompts/*.ts` | Agent prompts (research-agent, planner) |
 | `src/templates/claude-md.ts` | CLAUDE.md generation for new cases |
-| `src/tunnel-manager.ts` | Manages cloudflared child process for Cloudflare tunnel remote access |
 | `src/cli.ts` | Command-line interface handlers |
-| `src/web/server.ts` | Fastify REST API + SSE at `/api/events` (~280 routes) |
+| `src/web/server.ts` | Fastify REST API + SSE at `/api/events` (~105 routes) |
 | `src/web/schemas.ts` | Zod v4 validation schemas with path/env security allowlists |
-| `src/web/public/app.js` | Frontend: xterm.js, tab management, subagent windows, mobile support (~15K lines) |
+| `src/web/public/app.js` | Frontend: xterm.js, tab management, subagent windows, mobile support (~17K lines) |
 | `src/types.ts` | All TypeScript interfaces (~70 type/interface/enum defs, ~1450 lines) |
 
 **Large files** (>50KB): `app.js`, `ralph-tracker.ts`, `respawn-controller.ts`, `session.ts`, `subagent-watcher.ts` — these contain complex state machines; read `docs/respawn-state-machine.md` before modifying.
@@ -172,23 +163,22 @@ journalctl --user -u codeman-web -f
 | `buffer-limits.ts` | Terminal/text buffer size limits |
 | `map-limits.ts` | Global limits for Maps, sessions, watchers |
 
-### Utilities (`src/utils/`)
+### Utility Files (`src/utils/`)
 
-Re-exported via `src/utils/index.ts`. Key exports:
-
-| File | Exports |
+| File | Purpose |
 |------|---------|
-| `cleanup-manager.ts` | `CleanupManager` — centralized disposal for timers, intervals, watchers, listeners, streams |
-| `lru-map.ts` | `LRUMap` — bounded cache with eviction |
-| `stale-expiration-map.ts` | `StaleExpirationMap` — TTL-based map with automatic cleanup |
-| `regex-patterns.ts` | `ANSI_ESCAPE_PATTERN_FULL/SIMPLE`, `createAnsiPatternFull/Simple()`, `stripAnsi`, `TOKEN_PATTERN`, `SPINNER_PATTERN` |
-| `buffer-accumulator.ts` | `BufferAccumulator` — batches rapid writes into single flushes |
-| `claude-cli-resolver.ts` | `findClaudeDir`, `getAugmentedPath` — resolves Claude CLI paths |
-| `opencode-cli-resolver.ts` | `resolveOpenCodeDir`, `isOpenCodeAvailable` — OpenCode CLI support |
-| `string-similarity.ts` | `stringSimilarity`, `fuzzyPhraseMatch`, `todoContentHash` |
-| `token-validation.ts` | `validateTokenCounts`, `validateTokensAndCost` |
-| `nice-wrapper.ts` | `wrapWithNice` — wraps commands with `nice`/`ionice` for lower priority |
-| `type-safety.ts` | `assertNever` — exhaustive switch/case guard |
+| `index.ts` | Re-exports all utilities (standard import point) |
+| `lru-map.ts` | LRU eviction Map for bounded caches |
+| `nice-wrapper.ts` | Wrap commands with `nice` priority adjustment |
+| `stale-expiration-map.ts` | TTL-based Map with lazy expiration |
+| `claude-cli-resolver.ts` | Resolve Claude CLI binary across install paths |
+| `cleanup-manager.ts` | Centralized resource disposal |
+| `buffer-accumulator.ts` | Chunk accumulator with size limits |
+| `string-similarity.ts` | String matching utilities (fuzzy matching) |
+| `token-validation.ts` | Token count parsing and validation |
+| `regex-patterns.ts` | Shared regex patterns for parsing |
+| `type-safety.ts` | `assertNever()` for exhaustive switch/case type checking |
+| `opencode-cli-resolver.ts` | Resolve OpenCode CLI binary across install paths |
 
 ### Data Flow
 
@@ -224,8 +214,7 @@ Re-exported via `src/utils/index.ts`. Key exports:
 | File | Purpose |
 |------|---------|
 | `src/web/public/index.html` | HTML entry point with inline critical CSS and async vendor loading |
-| `src/web/public/app.js` | Core UI: xterm.js, tab management, subagent windows, mobile support (~15K lines) |
-| `src/web/public/ralph-wizard.js` | Ralph Loop wizard UI extracted from app.js (~1K lines) |
+| `src/web/public/app.js` | Core UI: xterm.js, tab management, subagent windows, mobile support (~17.5K lines) |
 | `src/web/public/styles.css` | Main styling (dark theme, layout, components) |
 | `src/web/public/mobile.css` | Responsive overrides for screens <1024px (loaded conditionally via `media` attribute) |
 | `src/web/public/upload.html` | Screenshot upload page served at `/upload.html` |
@@ -235,7 +224,7 @@ Re-exported via `src/utils/index.ts`. Key exports:
 
 ### Frontend Architecture (`app.js`)
 
-The frontend is a single ~15K-line vanilla JS file with these key systems:
+The frontend is a single ~17.5K-line vanilla JS file with these key systems:
 
 | System | Key Classes/Functions | Purpose |
 |--------|----------------------|---------|
@@ -284,7 +273,7 @@ The frontend is a single ~15K-line vanilla JS file with these key systems:
 
 ### API Route Categories
 
-~280 route handlers in `server.ts:buildServer()`. Key groups:
+~105 routes in `server.ts:buildServer()`. Key groups:
 
 | Group | Prefix | Count | Key endpoints |
 |-------|--------|-------|---------------|
@@ -441,42 +430,58 @@ Use `LRUMap` for bounded caches with eviction, `StaleExpirationMap` for TTL-base
 | **Ralph Loop guide** | `docs/ralph-wiggum-guide.md` |
 | **Claude Code hooks** | `docs/claude-code-hooks-reference.md` |
 | **Terminal anti-flicker** | `docs/terminal-anti-flicker.md` |
-| **Agent Teams (experimental)** | `agent-teams/README.md`, `agent-teams/design.md` |
-| **API routes** | `src/web/server.ts:buildServer()` or README.md |
+| **API routes** | `src/web/server.ts:buildServer()` or README.md (full endpoint tables) |
 | **SSE events** | Search `broadcast(` in `server.ts` |
+| **CLI commands** | `codeman --help` |
+| **Frontend patterns** | `src/web/public/app.js` (subagent windows, notifications) |
 | **Session statuses** | `SessionStatus` type in `src/types.ts` |
 | **Error codes** | `createErrorResponse()` in `src/types.ts` |
 | **Test utilities** | `test/respawn-test-utils.ts` |
-| **Mobile test suite** | `mobile-test/README.md` |
-| **OpenCode integration** | `docs/opencode-integration.md` |
+| **Memory leak patterns** | `test/memory-leak-prevention.test.ts` |
+| **Keyboard shortcuts** | README.md or App Settings in web UI |
+| **Mobile/SSH access** | README.md (Codeman Sessions / `sc` command) |
+| **Plan orchestrator** | `src/plan-orchestrator.ts` file header |
+| **Agent prompts** | `src/prompts/` directory |
+| **Agent Teams (experimental)** | `agent-teams/README.md`, `agent-teams/design.md` |
 | **Local echo overlay** | `docs/local-echo-overlay-plan.md` |
-| **Performance investigation** | `docs/performance-investigation-report.md` |
-| **First-load optimization** | `docs/first-load-optimization-plan.md`, `docs/perf-audit-first-load.md` |
-| **Dead code audit** | `docs/cleanup-findings.md` |
-| **TypeScript improvements** | `docs/typescript-improvement-suggestions.md` |
 | **Browser testing** | `docs/browser-testing-guide.md` |
-| **Mobile testing report** | `docs/mobile-testing-report.md` |
+| **Mobile testing** | `docs/mobile-testing-report.md` |
+| **Run summary design** | `docs/run-summary-plan.md` |
+| **Performance audit** | `docs/perf-audit-first-load.md` |
+| **First-load optimization** | `docs/first-load-optimization-plan.md` |
+| **Dead code audit** | `docs/cleanup-findings.md` |
+| **Mobile test suite** | `mobile-test/README.md` |
 | **Voice input** | `docs/voice-input-plan.md` |
-| **Improvement roadmaps** | `docs/respawn-improvement-plan.md`, `docs/ralph-improvement-plan.md`, `docs/plan-improvement-roadmap.md` |
 | **Background keystroke forwarding** | `docs/background-keystroke-forwarding-merged-plan.md` |
-| **Run summary** | `docs/run-summary-plan.md` |
-
-Additional design docs and investigation reports are in the `docs/` directory.
+| **Respawn improvements** | `docs/respawn-improvement-plan.md` |
+| **Ralph improvements** | `docs/ralph-improvement-plan.md`, `docs/ralph-phase1-implementation.md` |
+| **Performance investigation** | `docs/performance-investigation-report.md` |
+| **Plan improvements** | `docs/plan-improvement-roadmap.md` |
+| **TypeScript improvements** | `docs/typescript-improvement-suggestions.md` |
+| **OpenCode integration** | `docs/opencode-integration.md` |
 
 ## Scripts
 
 | Script | Purpose |
 |--------|---------|
 | `scripts/tmux-manager.sh` | Safe tmux session management (use instead of direct kill commands) |
+| `scripts/tmux-chooser.sh` | Mobile-friendly tmux session picker (`sc` alias) |
 | `scripts/monitor-respawn.sh` | Monitor respawn state machine in real-time |
-| `scripts/watch-subagents.ts` | Real-time subagent transcript watcher (list, follow by session/agent ID) |
-| `scripts/codeman-web.service` | systemd service file for production deployment |
-| `scripts/codeman-tunnel.service` | systemd service file for persistent Cloudflare tunnel |
-| `scripts/tunnel.sh` | Start/stop/check Cloudflare quick tunnel (`./scripts/tunnel.sh start\|stop\|url`) |
-| `scripts/build.mjs` | esbuild-based production build (called by `npm run build`) |
 | `scripts/postinstall.js` | npm postinstall hook for setup |
-
-Additional scripts in `scripts/` for screenshots, demos, Ralph wizards, and browser testing.
+| `scripts/data-generator.sh` | Generate test data for development |
+| `scripts/test-tail-links.sh` | Test clickable file links in tail output |
+| `scripts/capture-subagent-screenshots.mjs` | Capture subagent screenshots for README (uses real Claude sessions) |
+| `scripts/capture-subagent-gif.mjs` | Capture subagent GIF animations for README |
+| `scripts/mobile-screenshot.mjs` | Capture mobile UI screenshots |
+| `scripts/ralph-wizard-start.mjs` | Automate Ralph Loop startup via headless browser |
+| `scripts/ralph-wizard-prod.mjs` | Production Ralph wizard with HTTPS support |
+| `scripts/browser-comparison.mjs` | Compare Playwright, Puppeteer, and Agent-Browser frameworks |
+| `scripts/ralph-wizard-demo.mjs` | Demo Ralph Loop wizard via visible browser |
+| `scripts/test-links-browser.mjs` | Browser test for clickable terminal file links |
+| `scripts/test-patterns.mjs` | Test file path link detection regex patterns |
+| `scripts/watch-subagents.ts` | Real-time subagent transcript watcher (list, follow by session/agent ID) |
+| `scripts/capture-readme-screenshots.mjs` | Capture screenshots for README |
+| `scripts/codeman-web.service` | systemd service file for production deployment |
 
 ## Memory Leak Prevention
 

README.md

@@ -194,53 +194,6 @@ PTY Output → 16ms Server Batch → DEC 2026 Wrap → SSE → Client rAF → xt
 
 ---
 
-## Remote Access — Cloudflare Tunnel
-
-Access Codeman from your phone or any device outside your local network using a free [Cloudflare quick tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/) — no port forwarding, no DNS, no static IP required.
-
-```
-Browser (phone/tablet) → Cloudflare Edge (HTTPS) → cloudflared → localhost:3000
-```
-
-**Prerequisites:** Install [`cloudflared`](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) and set `CODEMAN_PASSWORD` in your environment.
-
-```bash
-# Quick start
-./scripts/tunnel.sh start      # Start tunnel, prints public URL
-./scripts/tunnel.sh url        # Show current URL
-./scripts/tunnel.sh stop       # Stop tunnel
-./scripts/tunnel.sh status     # Service status + URL
-```
-
-The script auto-installs a systemd user service on first run. The tunnel URL is a randomly generated `*.trycloudflare.com` address that changes each time the tunnel restarts.
-
-<details>
-<summary><strong>Persistent tunnel (survives reboots)</strong></summary>
-
-```bash
-# Enable as a persistent service
-systemctl --user enable codeman-tunnel
-loginctl enable-linger $USER
-
-# Or via the Codeman web UI: Settings → Tunnel → Toggle On
-```
-
-</details>
-
-<details>
-<summary><strong>Authentication</strong></summary>
-
-1. First request → browser shows Basic Auth prompt (username: `admin` or `CODEMAN_USERNAME`)
-2. On success → server issues a `codeman_session` cookie (24h TTL, auto-extends on activity)
-3. Subsequent requests authenticate silently via cookie
-4. 10 failed attempts per IP → 429 rate limit (15-minute decay)
-
-**Always set `CODEMAN_PASSWORD`** before exposing via tunnel — without it, anyone with the URL has full access to your sessions.
-
-</details>
-
----
-
 ## SSH Alternative (`sc`)
 
 If you prefer SSH (Termius, Blink, etc.), the `sc` command is a thumb-friendly session chooser:

docs/performance-optimization-plan.md

@@ -1,185 +0,0 @@
-# Performance & Responsiveness Optimization Plan
-
-**Date**: 2026-02-28
-**Status**: In Progress
-
----
-
-## Executive Summary
-
-Three independent research passes analyzed the Codeman codebase for performance bottlenecks across frontend rendering, backend hot paths, and system-level resource usage. The codebase already has strong foundational optimizations (per-session adaptive batching, rAF terminal writes, DEC 2026 sync markers, backpressure handling). This plan targets the remaining high-impact opportunities.
-
-**Key finding**: The biggest wins come from **skipping unnecessary work** — serializing unchanged state, processing output nobody is watching, and reducing broadcast volume.
-
----
-
-## Phase 1: Quick Wins — ALREADY IMPLEMENTED
-
-All Phase 1 items were found to already exist in the codebase during verification:
-
-| # | Item | Status | Evidence |
-|---|------|--------|----------|
-| 1.1 | Skip terminal writes for hidden tabs | Done | SSE handler filters by `activeSessionId` (app.js:4076) |
-| 1.2 | mobile.css media query | Done | `media="(max-width: 1023px)"` on link tag (index.html:13) |
-| 1.3 | Deduplicate init API calls | Done | `_initGeneration` dedup + 3s fallback timer (app.js:2901-2904) |
-| 1.4 | Remove cache-busting timestamps | Done | No `?_t=` patterns found anywhere |
-| 1.5 | JS/CSS minification + compression | Done | esbuild minify + gzip + brotli in build.mjs (lines 42-51) |
-
----
-
-## Phase 2: Frontend Responsiveness — MOSTLY ALREADY IMPLEMENTED
-
-### 2.1 Batch `getBoundingClientRect()` in connection lines — DONE
-- **Files**: `src/web/public/app.js` (`_updateConnectionLinesImmediate()`)
-- **Change**: Refactored to batch all layout reads into Phase 1 (collect all rects into a Map), then perform all SVG writes in Phase 2 using cached values. Classic read-then-write pattern prevents interleaved forced reflows.
-
-### 2.2 Clean up ResizeObservers — Already implemented
-- `forceCloseSubagentWindow()` disconnects observers (app.js:12618-12620)
-- `cleanupAllFloatingWindows()` disconnects all on reconnect (app.js:12649-12653)
-- Observer refs stored on `windowData.resizeObserver` (app.js:12492)
-
-### 2.3 Drag handler cleanup — Already implemented
-- `makeWindowDraggable()` returns listener refs, stored in `windowData.dragListeners`
-- `forceCloseSubagentWindow()` removes all document-level drag listeners (app.js:12622-12630)
-- Panel drags add listeners on mousedown, remove on mouseup (app.js:10253-10284)
-
-### 2.4 Mobile window position cache — Skipped
-- O(n) loop over max ~20 windows; complexity of cached counter not justified
-
-### 2.5 Lazy modal DOM — Skipped
-- Large effort, marginal benefit for a vanilla JS app with fast DOM construction
-
----
-
-## Phase 3: Backend Hot Paths
-
-### 3.1 State diff broadcasts — ALREADY OPTIMIZED
-- `broadcastSessionStateDebounced()` already batches at 500ms intervals
-- `toLightDetailedState()` excludes heavy buffers (textOutput, terminalBuffer)
-- Per-session serialization is <1ms; with debouncing, only 1-3 sessions serialize per flush
-- JSON.stringify happens once per broadcast (not per client) — serialization cost is negligible
-- Full state diffs would add significant frontend complexity for marginal gain
-
-### 3.2 Improve session list cache hit rate — DONE
-- **Files**: `src/web/server.ts` (`broadcast()` method)
-- **Change**: Cache now only invalidated on truly structural events (`session:created`, `session:deleted`, `session:updated`) instead of on every `session:*` and `respawn:*` event. High-frequency events like `session:working`, `session:idle`, `session:completion`, `respawn:stateChanged` no longer defeat the 1s TTL cache.
-- **Impact**: Cache hit ratio from ~0% to ~80%+ during active sessions. The debounced `session:updated` still refreshes the cache within 500ms of any state change.
-
-### 3.3 Skip PTY processing — ALREADY OPTIMIZED
-- `_processExpensiveParsers()` is already throttled to every 150ms (not per-chunk)
-- Lazy ANSI stripping via `getCleanData()` closure — only computed when a consumer needs it
-- Quick pre-checks skip parsers when content is irrelevant (e.g., token parser only runs if data contains "token")
-- OpenCode sessions skip all Claude-specific parsers entirely
-- Further optimization would require visibility-aware processing, adding complexity for marginal gain
-
-### 3.4 Batch subagent liveness checks — Deferred
-- `/proc/{pid}` stat calls are ~0.1ms each; even with 500 agents, total is 50ms every 10s
-- Current approach is simple and reliable; batching adds race condition risk
-- Consider only if profiling shows this as a bottleneck
-
-### 3.5 Deduplicate detection update emissions — DONE
-- **Files**: `src/respawn-controller.ts` (`startDetectionUpdates()`)
-- **Change**: Detection status now only emitted when key fields (confidenceLevel, statusText, controller state) actually change. Previously emitted every 2s regardless, broadcasting identical status to all SSE clients.
-- **Impact**: For stable/idle sessions, eliminates ~100% of redundant detection broadcasts. For active sessions, reduces broadcasts to only meaningful state transitions.
-
----
-
-## Phase 4: System-Level Improvements
-
-### 4.1 Incremental state persistence
-- **Files**: `src/state-store.ts` (~lines 145-160)
-- **Problem**: Every 500ms debounce writes the entire `AppState` (all sessions, tasks, config) via `JSON.stringify()`. With 50 sessions, state can be tens of MB. Serialization alone costs 50-100ms.
-- **Fix**: Track dirty sessions. On persist, only re-serialize dirty sessions; cache serialized JSON for clean sessions. Assemble final output from cached fragments.
-- **Impact**: Reduces serialization cost from O(all sessions) to O(dirty sessions). Typical steady-state: 1-2 dirty sessions instead of 50.
-
-### 4.2 Replace polling with fs watchers for team watcher
-- **Files**: `src/team-watcher.ts` (~lines 148-180)
-- **Problem**: Polls `~/.claude/teams/` every 5s via `readdir()` + `stat()`. Blocks event loop for 100-200ms on large directories.
-- **Fix**: Use `chokidar` (already a dependency) or `fs.watch()` to react to changes. Keep a 30s fallback poll for reliability.
-- **Impact**: Eliminates 5s polling overhead; near-instant team detection.
-
-### 4.3 Consolidate subagent file watchers
-- **Files**: `src/subagent-watcher.ts` (~line 229+)
-- **Problem**: One chokidar watcher per agent directory. With 500 agents, that's 500 inotify watchers consuming kernel resources.
-- **Fix**: Watch at the session level (one watcher per session's subagent directory), not per-agent. Parse events to route to correct agent.
-- **Impact**: Reduces inotify watchers from 500 to ~50 (one per session).
-
-### 4.4 Stream transcript files instead of full reads
-- **Files**: `src/subagent-watcher.ts` (~lines 959-964)
-- **Problem**: `loadTranscript()` reads entire transcript file (can be >100KB). With 500 agents discovered at once, that's 50MB of file reads.
-- **Fix**: Only read last 10KB for display (tail). Full file on-demand only (e.g., when user opens transcript viewer).
-- **Impact**: Reduces file I/O from 50MB to 5MB for bulk agent discovery.
-
----
-
-## Phase 5: Long-Term Architectural (Optional)
-
-### 5.1 Worker thread for PTY processing
-- **Files**: `src/session.ts`
-- **Problem**: ANSI stripping, Ralph tracking, and bash tool parsing all run on the main event loop. At scale (50 busy sessions), this consumes 300-500ms CPU/sec.
-- **Fix**: Offload ANSI strip + line processing to a worker thread pool. Main thread receives clean text + parsed events.
-- **Impact**: Frees event loop for I/O operations. Most impactful at 10+ concurrent busy sessions.
-
-### 5.2 Per-session SSE subscriptions
-- **Files**: `src/web/server.ts`
-- **Problem**: Every SSE event is broadcast to all connected clients. A client watching session A still receives events for sessions B through Z.
-- **Fix**: Clients subscribe to specific session IDs. Server only sends events to interested clients.
-- **Impact**: Reduces SSE broadcast fan-out from N clients to ~1-2 per event. Major improvement at 100 SSE clients.
-
-### 5.3 O(1) LRUMap via doubly-linked list
-- **Files**: `src/utils/lru-map.ts` (~lines 98-110)
-- **Problem**: `get()` uses delete + re-insert to refresh position — O(n) on Map iteration for delete.
-- **Fix**: Implement classic LRU with doubly-linked list + Map for O(1) get/put/evict.
-- **Impact**: Low — current sizes (max 500) make this barely measurable. Only worthwhile if LRUMap is used on hot paths.
-
----
-
-## Priority Matrix (Remaining Work)
-
-| # | Item | Impact | Risk | Effort |
-|---|------|--------|------|--------|
-| 3.1 | State diff broadcasts | **Very High** | Medium | 3-4h |
-| 3.2 | Fix session cache invalidation | **High** | Low | 1h |
-| 3.3 | Skip PTY processing for hidden sessions | **High** | Medium | 2-3h |
-| 3.5 | Throttle detection broadcasts | **Medium** | Low | 1h |
-| 3.4 | Batch liveness checks | **Medium** | Low | 1-2h |
-| 4.1 | Incremental state persistence | **Medium** | Medium | 3-4h |
-| 4.2 | Team watcher fs events | **Low-Med** | Medium | 2h |
-| 4.3 | Consolidate file watchers | **Low-Med** | Medium | 2h |
-| 4.4 | Stream transcripts | **Low-Med** | Low | 1h |
-| 5.1 | Worker thread PTY | **Med** (at scale) | High | 8h |
-| 5.2 | Per-session SSE subs | **Med** (at scale) | High | 4h |
-| 5.3 | O(1) LRUMap | **Very Low** | Medium | 2h |
-
----
-
-## Recommended Execution Order
-
-**Sprint 1** (Phase 3 — Backend Hot Paths): Items 3.1, 3.2, 3.3, 3.5
-- Backend serialization and broadcast efficiency
-- Highest remaining impact; requires careful testing with multiple active sessions
-
-**Sprint 2** (Phase 4 — System Level): Items 4.1, 3.4, 4.3, 4.4
-- State persistence, liveness checks, watcher consolidation
-- Medium-complexity refactors
-
-**Sprint 3** (Phase 5 — Architectural): Items 5.1, 5.2 — only if scaling demands it
-
----
-
-## Measurement
-
-Before starting implementation, establish baselines:
-
-1. **Frontend**: Record Chrome DevTools Performance trace with 10 sessions open. Measure:
-   - Frame rate during rapid terminal output
-   - Long tasks (>50ms) count per 30s
-   - Heap size after 1h session
-
-2. **Backend**: Add `performance.now()` instrumentation around:
-   - `flushSessionTerminalBatch()` — time per flush
-   - `broadcastSessionStateDebounced()` — serialization time
-   - `StateStore.save()` — persist time
-   - Event loop lag via `monitorEventLoopDelay()`
-
-3. **First load**: Lighthouse score on desktop and mobile (simulated 3G)

package-lock.json

@@ -1,16 +1,15 @@
 {
-  "name": "aicodeman",
-  "version": "0.2.8",
+  "name": "codeman",
+  "version": "0.2.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
-      "name": "aicodeman",
-      "version": "0.2.8",
+      "name": "codeman",
+      "version": "0.2.1",
       "hasInstallScript": true,
       "license": "MIT",
       "workspaces": [
-        ".",
         "packages/*"
       ],
       "dependencies": {
@@ -32,7 +31,7 @@
         "zod": "^4.3.6"
       },
       "bin": {
-        "aicodeman": "dist/index.js"
+        "codeman": "dist/index.js"
       },
       "devDependencies": {
         "@changesets/cli": "^2.29.8",
@@ -2480,10 +2479,6 @@
         "url": "https://github.com/sponsors/colinhacks"
       }
     },
-    "node_modules/aicodeman": {
-      "resolved": "",
-      "link": true
-    },
     "node_modules/ajv": {
       "version": "8.18.0",
       "license": "MIT",

package.json

@@ -1,12 +1,12 @@
 {
-  "name": "aicodeman",
-  "version": "0.2.9",
+  "name": "codeman",
+  "version": "0.2.1",
   "description": "The missing control plane for AI coding agents - run 20 autonomous agents with real-time monitoring and session persistence",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
-    "aicodeman": "./dist/index.js"
+    "codeman": "./dist/index.js"
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.js",
@@ -29,7 +29,6 @@
     "release": "changeset publish"
   },
   "workspaces": [
-    ".",
     "packages/*"
   ],
   "keywords": [

plan.json

@@ -0,0 +1,399 @@
+{
+  "items": [
+    {
+      "id": "P0-001",
+      "content": "Write failing tests for SessionMode type extension — verify 'opencode' is accepted as a valid mode in SessionMode, OpenCodeConfig interface exists with model/provider/autoAllowTools/continueSession/serverPort fields, and MuxSession.mode accepts 'opencode'",
+      "priority": "P0",
+      "tddPhase": "test",
+      "verificationCriteria": "test/opencode-types.test.ts exists, tests fail because SessionMode doesn't include 'opencode' and OpenCodeConfig doesn't exist",
+      "testCommand": "npx vitest run test/opencode-types.test.ts",
+      "dependencies": []
+    },
+    {
+      "id": "P0-002",
+      "content": "Implement SessionMode type extension — extend SessionMode from 'claude' | 'shell' to 'claude' | 'shell' | 'opencode' in types.ts (line 162), add OpenCodeConfig interface with fields: model?: string, provider?: string, autoAllowTools?: boolean, continueSession?: string, serverPort?: number. Update MuxSession.mode and createSession/respawnPane signatures in mux-interface.ts to accept 'opencode' and optional openCodeConfig param",
+      "priority": "P0",
+      "tddPhase": "impl",
+      "verificationCriteria": "npx vitest run test/opencode-types.test.ts passes, tsc --noEmit succeeds",
+      "pairedWith": "P0-001",
+      "dependencies": ["P0-001"]
+    },
+    {
+      "id": "P0-003",
+      "content": "Review type system changes — verify OpenCodeConfig follows existing type conventions (optional fields, no Claude-specific coupling), SessionMode union is used consistently across types.ts/mux-interface.ts/session.ts, no breaking changes to existing code",
+      "priority": "P0",
+      "tddPhase": "review",
+      "verificationCriteria": "tsc --noEmit passes with no errors, grep confirms SessionMode used consistently, no 'claude' | 'shell' hardcoded literals remain in interface definitions",
+      "reviewChecklist": ["Type consistency across files", "No breaking changes to existing Claude/shell modes", "OpenCodeConfig fields match opencode CLI flags", "Optional fields properly typed"],
+      "pairedWith": "P0-002",
+      "dependencies": ["P0-002"]
+    },
+    {
+      "id": "P0-004",
+      "content": "Write failing tests for OpenCode CLI resolver — test resolveOpenCodeDir() returns directory when opencode binary exists, returns null when not found, caches result after first call, isOpenCodeAvailable() returns boolean, getOpenCodeAugmentedPath() prepends directory to PATH. Mock filesystem and execSync. Port: none (pure unit test)",
+      "priority": "P0",
+      "tddPhase": "test",
+      "verificationCriteria": "test/opencode-resolver.test.ts exists with 5+ test cases, all fail because opencode-cli-resolver.ts doesn't exist",
+      "testCommand": "npx vitest run test/opencode-resolver.test.ts",
+      "dependencies": []
+    },
+    {
+      "id": "P0-005",
+      "content": "Implement opencode-cli-resolver.ts — create src/utils/opencode-cli-resolver.ts mirroring claude-cli-resolver.ts pattern. Functions: resolveOpenCodeDir() (checks which opencode, then ~/.local/bin, /usr/local/bin, ~/.bun/bin, ~/.npm-global/bin, ~/bin, ~/.opencode/bin), isOpenCodeAvailable(), getOpenCodeAugmentedPath(). Cache results. Add re-export in src/utils/index.ts",
+      "priority": "P0",
+      "tddPhase": "impl",
+      "verificationCriteria": "npx vitest run test/opencode-resolver.test.ts passes, tsc --noEmit succeeds",
+      "pairedWith": "P0-004",
+      "dependencies": ["P0-004"]
+    },
+    {
+      "id": "P0-006",
+      "content": "Review CLI resolver implementation — verify no command injection in execSync('which opencode'), timeout set to 5s, graceful fallback when binary not found, caching works correctly (null vs empty string sentinel), PATH augmentation doesn't duplicate entries",
+      "priority": "P0",
+      "tddPhase": "review",
+      "verificationCriteria": "Code review passes: no shell injection, proper error handling, cache invalidation, consistent with claude-cli-resolver.ts patterns",
+      "reviewChecklist": ["No command injection in execSync", "Proper timeout handling", "Cache sentinel value for 'not found'", "PATH deduplication", "Re-export in utils/index.ts"],
+      "pairedWith": "P0-005",
+      "dependencies": ["P0-005"]
+    },
+    {
+      "id": "P0-007",
+      "content": "Write failing tests for Zod schema validation — test CreateSessionSchema accepts mode: 'opencode', accepts openCodeConfig object with model/provider/autoAllowTools/continueSession fields, rejects invalid model strings (shell metacharacters), rejects overly long model names (>100 chars), validates provider field. Port: none (pure unit test)",
+      "priority": "P0",
+      "tddPhase": "test",
+      "verificationCriteria": "test/opencode-schema.test.ts exists, tests fail because schema doesn't accept 'opencode' mode or openCodeConfig field",
+      "testCommand": "npx vitest run test/opencode-schema.test.ts",
+      "dependencies": ["P0-002"]
+    },
+    {
+      "id": "P0-008",
+      "content": "Implement schema validation changes — update CreateSessionSchema in src/web/schemas.ts: extend mode enum to include 'opencode', add openCodeConfig z.object with model (string, max 100, regex /^[a-zA-Z0-9._\\-/]+$/), provider (string, max 50), autoAllowTools (boolean), continueSession (string, max 100, regex /^[a-zA-Z0-9_-]+$/). All fields optional",
+      "priority": "P0",
+      "tddPhase": "impl",
+      "verificationCriteria": "npx vitest run test/opencode-schema.test.ts passes, tsc --noEmit succeeds",
+      "pairedWith": "P0-007",
+      "dependencies": ["P0-007"]
+    },
+    {
+      "id": "P0-009",
+      "content": "Review schema validation — verify model regex blocks shell metacharacters (;|&$`), continueSession regex blocks path traversal, no overly permissive patterns, consistent with existing SAFE_PATH_PATTERN security approach in schemas.ts",
+      "priority": "P0",
+      "tddPhase": "review",
+      "verificationCriteria": "Schema rejects all dangerous inputs: model with semicolons, backticks, pipes; continueSession with ../; empty strings handled properly",
+      "reviewChecklist": ["Shell metacharacter blocking", "Path traversal prevention", "Consistent with existing security patterns", "Zod v4 API usage correct"],
+      "pairedWith": "P0-008",
+      "dependencies": ["P0-008"]
+    },
+    {
+      "id": "P1-001",
+      "content": "Write failing tests for TmuxManager opencode command construction — test buildOpenCodeCommand() generates correct CLI: basic 'opencode' command, with --model flag, with --session flag for continue, validates model string safety, validates session ID safety. Test that createSession() with mode 'opencode' builds correct tmux respawn-pane command with opencode env vars (CLAUDEMAN_MUX, API keys passthrough). Mock execAsync. Port: none (unit test with mocks)",
+      "priority": "P1",
+      "tddPhase": "test",
+      "verificationCriteria": "test/opencode-tmux.test.ts exists with 8+ test cases covering command construction, env var setup, and PATH augmentation for opencode mode",
+      "testCommand": "npx vitest run test/opencode-tmux.test.ts",
+      "dependencies": ["P0-002", "P0-005"]
+    },
+    {
+      "id": "P1-002",
+      "content": "Implement TmuxManager opencode support — in src/tmux-manager.ts: (1) import resolveOpenCodeDir from utils, (2) add buildOpenCodeCommand(sessionId, config?) helper that constructs 'opencode [--model X] [--session Y]' with input validation, (3) extend createSession() command construction to handle mode === 'opencode' alongside existing claude/shell branches, (4) add opencode-specific env exports (CLAUDEMAN_MUX, CLAUDEMAN_SESSION_ID, API key passthrough for ANTHROPIC/OPENAI/GOOGLE_API_KEY, optional OPENCODE_CONFIG_CONTENT), (5) use resolveOpenCodeDir() for PATH augmentation when mode is opencode, (6) throw clear error if opencode binary not found, (7) apply same changes to respawnPane()",
+      "priority": "P1",
+      "tddPhase": "impl",
+      "verificationCriteria": "npx vitest run test/opencode-tmux.test.ts passes, tsc --noEmit succeeds",
+      "pairedWith": "P1-001",
+      "dependencies": ["P1-001"]
+    },
+    {
+      "id": "P1-003",
+      "content": "Review TmuxManager opencode integration — verify command injection prevention in buildOpenCodeCommand (model and sessionId validated before interpolation), env var escaping for OPENCODE_CONFIG_CONTENT (single quotes properly escaped), API key passthrough doesn't leak other env vars, respawnPane changes mirror createSession exactly, error messages are actionable",
+      "priority": "P1",
+      "tddPhase": "review",
+      "verificationCriteria": "No command injection vectors, env vars properly escaped, consistent with existing Claude command construction security, error messages guide user to install opencode",
+      "reviewChecklist": ["Command injection prevention", "Env var escaping (single quotes in config content)", "API key passthrough scope limited", "respawnPane mirrors createSession", "Error message includes install instructions"],
+      "pairedWith": "P1-002",
+      "dependencies": ["P1-002"]
+    },
+    {
+      "id": "P1-004",
+      "content": "Write failing tests for Session class opencode mode — test that Session constructor accepts mode: 'opencode' with openCodeConfig, test startInteractive() dispatches to opencode-specific startup (not Claude CLI), test that Claude-specific features are disabled for opencode sessions (hooks config skipped, subagent watcher Claude patterns skipped), test that writeViaMux() works identically for opencode mode (tmux send-keys is mode-agnostic). Port: 3161",
+      "priority": "P1",
+      "tddPhase": "test",
+      "verificationCriteria": "test/opencode-session.test.ts exists with 6+ test cases, tests fail because Session doesn't support opencode mode",
+      "testCommand": "npx vitest run test/opencode-session.test.ts",
+      "dependencies": ["P0-002", "P1-002"]
+    },
+    {
+      "id": "P1-005",
+      "content": "Implement Session class opencode support — in src/session.ts: (1) accept openCodeConfig in constructor options and store as private field, (2) in startInteractive(), when mode is 'opencode', pass openCodeConfig to mux.createSession(), (3) skip hooks config generation for opencode sessions (no .claude/settings.local.json hooks), (4) add waitForOpenCodeReady() method using output-silence detection (wait for TUI paint: 500ms of stable output after initial burst, max 8s), (5) skip Claude-specific status line parsing for opencode mode, (6) add mode getter to Session for downstream consumers",
+      "priority": "P1",
+      "tddPhase": "impl",
+      "verificationCriteria": "npx vitest run test/opencode-session.test.ts passes, tsc --noEmit succeeds",
+      "pairedWith": "P1-004",
+      "dependencies": ["P1-004"]
+    },
+    {
+      "id": "P1-006",
+      "content": "Review Session class opencode integration — verify opencode mode doesn't break existing Claude/shell sessions (no regressions), waitForOpenCodeReady timeout is reasonable (8s), hooks are properly skipped without breaking Claude hooks, no memory leaks from new fields, toState() includes opencode-relevant state",
+      "priority": "P1",
+      "tddPhase": "review",
+      "verificationCriteria": "Existing session tests still pass, opencode-specific logic properly guarded with mode checks, no side effects on Claude sessions",
+      "reviewChecklist": ["No regression on Claude/shell modes", "waitForOpenCodeReady timeout appropriate", "Hooks skipped cleanly", "toState() serialization works", "No memory leak from new fields"],
+      "pairedWith": "P1-005",
+      "dependencies": ["P1-005"]
+    },
+    {
+      "id": "P1-007",
+      "content": "Write failing tests for opencode idle detection — test getIdleDetectionConfig() returns opencode-specific config (silenceThresholdMs: 5000, no prompt pattern, no AI checker), test that session emits 'idle' after 5s of output silence in opencode mode, test that session emits 'working' when output resumes, test that idle detection works during respawn cycles. Port: 3162",
+      "priority": "P1",
+      "tddPhase": "test",
+      "verificationCriteria": "test/opencode-idle.test.ts exists with 4+ test cases testing silence-based idle detection for opencode mode",
+      "testCommand": "npx vitest run test/opencode-idle.test.ts",
+      "dependencies": ["P1-005"]
+    },
+    {
+      "id": "P1-008",
+      "content": "Implement opencode idle detection — in src/session.ts: (1) add getIdleDetectionConfig() method returning mode-specific config: for opencode — silenceThresholdMs: 5000, promptPattern: null, useAIChecker: false; for claude — existing values, (2) modify idle detection logic to use silence-based detection when promptPattern is null (track lastOutputTime, timer-based idle check), (3) ensure 'working' event fires on any new output after idle state, (4) make IDLE_DETECTION_DELAY_MS configurable per mode",
+      "priority": "P1",
+      "tddPhase": "impl",
+      "verificationCriteria": "npx vitest run test/opencode-idle.test.ts passes, opencode sessions correctly transition idle→working→idle based on output silence",
+      "pairedWith": "P1-007",
+      "dependencies": ["P1-007"]
+    },
+    {
+      "id": "P1-009",
+      "content": "Review idle detection implementation — verify silence timer is properly cleaned up on session stop/exit (no leaked timers), timer doesn't fire after session disposal, idle threshold is tunable per session, working→idle transition doesn't spam events, existing Claude idle detection unchanged",
+      "priority": "P1",
+      "tddPhase": "review",
+      "verificationCriteria": "Timer cleanup verified, no event spam, Claude idle detection regression-free, CleanupManager tracks new timer",
+      "reviewChecklist": ["Timer cleanup on session.stop()", "No event spam on rapid output", "Claude idle detection unchanged", "CleanupManager integration", "Configurable threshold"],
+      "pairedWith": "P1-008",
+      "dependencies": ["P1-008"]
+    },
+    {
+      "id": "P1-010",
+      "content": "Write failing tests for API routes — test POST /api/sessions creates opencode session when mode: 'opencode', test returns 400 when opencode not installed, test GET /api/opencode/status returns availability info, test POST /api/sessions/:id/interactive works for opencode sessions, test openCodeConfig is persisted in session state. Port: 3163",
+      "priority": "P1",
+      "tddPhase": "test",
+      "verificationCriteria": "test/opencode-api.test.ts exists with 5+ test cases, tests fail because server doesn't handle opencode mode",
+      "testCommand": "npx vitest run test/opencode-api.test.ts",
+      "dependencies": ["P0-008", "P1-005"]
+    },
+    {
+      "id": "P1-011",
+      "content": "Implement API routes for opencode — in src/web/server.ts: (1) in POST /api/sessions handler, check isOpenCodeAvailable() when mode is 'opencode' and return 400 if not installed, pass openCodeConfig from request body to Session constructor, (2) add GET /api/opencode/status route returning { available: boolean, path: string | null }, (3) ensure POST /api/sessions/:id/interactive works for opencode mode (startInteractive already handles mode dispatch), (4) include mode in session state broadcast events, (5) persist openCodeConfig in state store",
+      "priority": "P1",
+      "tddPhase": "impl",
+      "verificationCriteria": "npx vitest run test/opencode-api.test.ts passes, curl GET /api/opencode/status returns valid JSON",
+      "pairedWith": "P1-010",
+      "dependencies": ["P1-010"]
+    },
+    {
+      "id": "P1-012",
+      "content": "Review API routes — verify /api/opencode/status doesn't expose sensitive info (only binary path, not env vars), session creation validates all openCodeConfig fields before passing to Session, error messages don't leak internal paths, SSE events include mode for frontend routing, state persistence includes openCodeConfig",
+      "priority": "P1",
+      "tddPhase": "review",
+      "verificationCriteria": "No info leakage, proper validation, error messages user-friendly, SSE events tagged with mode",
+      "reviewChecklist": ["No sensitive info in /api/opencode/status", "openCodeConfig validated before use", "Error messages actionable", "SSE events include mode", "State persistence round-trips correctly"],
+      "pairedWith": "P1-011",
+      "dependencies": ["P1-011"]
+    },
+    {
+      "id": "P1-013",
+      "content": "Write failing tests for frontend mode selector — Playwright test: load app, verify session creation dialog includes 'OpenCode' option alongside 'Claude Code' and 'Shell', verify selecting OpenCode shows model input field, verify OpenCode option is disabled when /api/opencode/status returns available: false, verify tab shows 'OC' badge for opencode sessions. Port: 3164",
+      "priority": "P1",
+      "tddPhase": "test",
+      "verificationCriteria": "test/opencode-frontend.test.ts (Playwright) exists with 4+ assertions, tests fail because UI doesn't have OpenCode option",
+      "testCommand": "npx vitest run test/opencode-frontend.test.ts",
+      "dependencies": ["P1-011"]
+    },
+    {
+      "id": "P1-014",
+      "content": "Implement frontend UI changes — in src/web/public/app.js: (1) add OpenCode to session creation mode selector (in quick-start modal and/or new session dialog), with icon and 'Multi-model AI agent' description, (2) when opencode mode selected, show model text input with autocomplete for common models (anthropic/claude-sonnet-4-5, openai/gpt-5.2, google/gemini-3-pro, ollama/codellama), (3) check /api/opencode/status on load and disable option if unavailable, (4) add tab badge rendering: 'OC' badge with green (#10b981) background for opencode sessions, 'SH' for shell, none for claude, (5) gate Claude-specific UI panels for opencode sessions (disable hooks panel, auto-compact button)",
+      "priority": "P1",
+      "tddPhase": "impl",
+      "verificationCriteria": "npx vitest run test/opencode-frontend.test.ts passes, manual verification: mode selector shows OpenCode option, tab badge renders",
+      "pairedWith": "P1-013",
+      "dependencies": ["P1-013"]
+    },
+    {
+      "id": "P1-015",
+      "content": "Review frontend implementation — verify mode selector accessibility (keyboard navigable, ARIA labels), model autocomplete doesn't make excessive API calls, tab badge CSS follows existing z-index layering, disabled state has clear visual indicator, no XSS from model name rendering (text content, not innerHTML), feature gating doesn't break Claude session UI",
+      "priority": "P1",
+      "tddPhase": "review",
+      "verificationCriteria": "Accessible UI, no XSS vectors, existing Claude UI unchanged, CSS consistent with design system",
+      "reviewChecklist": ["Keyboard accessibility", "No XSS from model names", "CSS z-index consistent", "Claude UI regression-free", "Disabled state visual clarity", "Mobile layout compatibility"],
+      "pairedWith": "P1-014",
+      "dependencies": ["P1-014"]
+    },
+    {
+      "id": "P1-016",
+      "content": "Write failing tests for respawn controller opencode adaptation — using MockSession from test/respawn-test-utils.ts: test respawn controller accepts opencode sessions, test completion detection uses output silence (not 'Worked for' pattern) for opencode, test prompt sending via writeViaMux works for opencode, test circuit breaker works identically for opencode sessions. Port: none (uses MockSession)",
+      "priority": "P1",
+      "tddPhase": "test",
+      "verificationCriteria": "test/opencode-respawn.test.ts exists with 4+ test cases using MockSession, tests fail because respawn controller doesn't handle opencode idle detection",
+      "testCommand": "npx vitest run test/opencode-respawn.test.ts",
+      "dependencies": ["P1-008"]
+    },
+    {
+      "id": "P1-017",
+      "content": "Implement respawn controller opencode adaptation — in src/respawn-controller.ts: (1) add mode-aware completion detection: for opencode, use output silence threshold instead of COMPLETION_TIME_PATTERN regex, (2) skip plan mode detection patterns for opencode (OpenCode has different plan mode), (3) skip AI idle checker for opencode sessions initially (prompt is Claude-specific), (4) ensure prompt sending via writeViaMux works without modification (it's mode-agnostic), (5) keep circuit breaker, health scoring, and cycle metrics unchanged (they're mode-agnostic)",
+      "priority": "P1",
+      "tddPhase": "impl",
+      "verificationCriteria": "npx vitest run test/opencode-respawn.test.ts passes, respawn cycles work with silence-based completion detection",
+      "pairedWith": "P1-016",
+      "dependencies": ["P1-016"]
+    },
+    {
+      "id": "P1-018",
+      "content": "Review respawn controller changes — verify existing Claude respawn behavior unchanged (run existing respawn tests), silence-based detection has reasonable timeout (matches idle detection config), no race conditions between idle detection and respawn timer, circuit breaker still functions correctly for opencode sessions",
+      "priority": "P1",
+      "tddPhase": "review",
+      "verificationCriteria": "Existing respawn tests pass, no regressions, silence timeout configurable, race conditions addressed",
+      "reviewChecklist": ["Existing Claude respawn tests pass", "Silence timeout reasonable", "No race conditions", "Circuit breaker works for opencode", "Respawn config serialization includes mode"],
+      "pairedWith": "P1-017",
+      "dependencies": ["P1-017"]
+    },
+    {
+      "id": "P1-019",
+      "content": "Write failing tests for state persistence round-trip — test that opencode sessions are correctly serialized to ~/.claudeman/state.json (mode, openCodeConfig preserved), test that sessions are restored on server restart with correct mode and config, test that session lifecycle log records opencode mode. Port: none (unit test)",
+      "priority": "P1",
+      "tddPhase": "test",
+      "verificationCriteria": "test/opencode-state.test.ts exists with 3+ test cases, tests verify serialization/deserialization of opencode session state",
+      "testCommand": "npx vitest run test/opencode-state.test.ts",
+      "dependencies": ["P1-005"]
+    },
+    {
+      "id": "P1-020",
+      "content": "Implement state persistence for opencode sessions — in src/state-store.ts: ensure openCodeConfig is included in SessionState serialization, in session.ts toState() method include openCodeConfig, in server.ts restoreSession() handle mode: 'opencode' and pass openCodeConfig through, update session-lifecycle-log.ts to record opencode mode in lifecycle entries",
+      "priority": "P1",
+      "tddPhase": "impl",
+      "verificationCriteria": "npx vitest run test/opencode-state.test.ts passes, state.json correctly stores and restores opencode sessions",
+      "pairedWith": "P1-019",
+      "dependencies": ["P1-019"]
+    },
+    {
+      "id": "P1-021",
+      "content": "Review state persistence — verify openCodeConfig doesn't contain sensitive data (API keys not serialized to disk), state.json schema is backward compatible (existing sessions load fine without openCodeConfig), lifecycle log entries are queryable by mode",
+      "priority": "P1",
+      "tddPhase": "review",
+      "verificationCriteria": "No API keys in state.json, backward compatibility verified, lifecycle log works",
+      "reviewChecklist": ["No secrets in state.json", "Backward compatibility", "Lifecycle log queryable by mode", "toState() round-trip fidelity"],
+      "pairedWith": "P1-020",
+      "dependencies": ["P1-020"]
+    },
+    {
+      "id": "P2-001",
+      "content": "Write failing tests for feature gating — test that hooks config is NOT generated for opencode sessions, test that subagent watcher skips Claude-specific transcript patterns for opencode, test that auto-compact sends correct slash command per mode (/compact for claude, /clear for opencode), test that token tracking is disabled for opencode sessions (no status line parsing). Port: none (unit tests)",
+      "priority": "P2",
+      "tddPhase": "test",
+      "verificationCriteria": "test/opencode-feature-gating.test.ts exists with 4+ test cases verifying mode-aware feature behavior",
+      "testCommand": "npx vitest run test/opencode-feature-gating.test.ts",
+      "dependencies": ["P1-005"]
+    },
+    {
+      "id": "P2-002",
+      "content": "Implement feature gating for opencode sessions — (1) in hooks-config.ts: guard generateHooksConfig() to skip when session mode is 'opencode', (2) in session.ts: skip token tracking / status line parsing for opencode mode, (3) in session.ts: make auto-compact command mode-aware (Claude: /compact, OpenCode: skip or /clear), (4) in subagent-watcher.ts: skip Claude-specific transcript parsing for opencode sessions but still watch for generic agent activity patterns",
+      "priority": "P2",
+      "tddPhase": "impl",
+      "verificationCriteria": "npx vitest run test/opencode-feature-gating.test.ts passes, Claude features properly disabled for opencode sessions",
+      "pairedWith": "P2-001",
+      "dependencies": ["P2-001"]
+    },
+    {
+      "id": "P2-003",
+      "content": "Review feature gating — verify all mode checks are consistent (use session.mode, not hardcoded string comparisons scattered everywhere), no Claude features accidentally leak into opencode sessions, no opencode-specific code paths break Claude sessions",
+      "priority": "P2",
+      "tddPhase": "review",
+      "verificationCriteria": "Consistent mode checking pattern, no feature leakage, no Claude regressions",
+      "reviewChecklist": ["Consistent mode check pattern", "No feature leakage", "No Claude regressions", "Auto-compact behavior correct per mode"],
+      "pairedWith": "P2-002",
+      "dependencies": ["P2-002"]
+    },
+    {
+      "id": "P2-004",
+      "content": "Write end-to-end integration test — Playwright test that creates an opencode session via the web UI (if opencode is installed) or via API with mocked binary, verifies terminal renders, sends input, receives output, verifies tab badge shows 'OC', verifies session appears in /api/sessions with mode: 'opencode', cleans up session. Port: 3165",
+      "priority": "P2",
+      "tddPhase": "test",
+      "verificationCriteria": "test/opencode-e2e.test.ts exists with full session lifecycle test, skips gracefully if opencode binary not installed",
+      "testCommand": "npx vitest run test/opencode-e2e.test.ts",
+      "dependencies": ["P1-014", "P1-011"]
+    },
+    {
+      "id": "P2-005",
+      "content": "Fix any issues found during E2E testing — address xterm.js rendering issues with OpenCode's Bubble Tea TUI (if any), fix signal handling (SIGWINCH for resize), resolve any env var passthrough issues, ensure cleanup on session delete works correctly for opencode sessions",
+      "priority": "P2",
+      "tddPhase": "impl",
+      "verificationCriteria": "npx vitest run test/opencode-e2e.test.ts passes end-to-end, manual smoke test confirms TUI renders correctly in browser",
+      "pairedWith": "P2-004",
+      "dependencies": ["P2-004"]
+    },
+    {
+      "id": "P2-006",
+      "content": "Review E2E integration — verify session cleanup doesn't leave orphaned tmux sessions, no zombie processes, state.json is clean after deletion, SSE events fire correctly for all lifecycle phases (created, interactive, idle, working, exit, deleted)",
+      "priority": "P2",
+      "tddPhase": "review",
+      "verificationCriteria": "No orphaned tmux sessions, no zombies, clean state.json after delete, all SSE events fire",
+      "reviewChecklist": ["No orphaned tmux sessions", "No zombie processes", "State cleanup complete", "SSE event lifecycle complete", "Resource usage reasonable"],
+      "pairedWith": "P2-005",
+      "dependencies": ["P2-005"]
+    },
+    {
+      "id": "P2-007",
+      "content": "Write tests for Ralph Loop opencode compatibility — test that Ralph Loop can send prompts to opencode sessions via writeViaMux, test that completion detection uses silence-based approach, test that todo tracking is disabled for opencode (no TodoWrite tool parsing), test that Ralph queue processes tasks for opencode sessions",
+      "priority": "P2",
+      "tddPhase": "test",
+      "verificationCriteria": "test/opencode-ralph.test.ts exists with 4+ test cases using MockSession configured in opencode mode",
+      "testCommand": "npx vitest run test/opencode-ralph.test.ts",
+      "dependencies": ["P1-017"]
+    },
+    {
+      "id": "P2-008",
+      "content": "Implement Ralph Loop opencode compatibility — in ralph-loop.ts: (1) allow opencode sessions to be Ralph Loop targets, (2) skip promise phrase detection for opencode (no <promise> tags), (3) use silence-based completion detection matching respawn controller approach, (4) skip TodoWrite parsing for opencode sessions, (5) keep task queue and priority logic unchanged (mode-agnostic)",
+      "priority": "P2",
+      "tddPhase": "impl",
+      "verificationCriteria": "npx vitest run test/opencode-ralph.test.ts passes, Ralph Loop can drive opencode sessions through task queues",
+      "pairedWith": "P2-007",
+      "dependencies": ["P2-007"]
+    },
+    {
+      "id": "P2-009",
+      "content": "Review Ralph Loop adaptation — verify Ralph Loop reliability for opencode (silence detection may be less precise than completion phrase), verify no Ralph features accidentally break for Claude sessions, verify circuit breaker properly handles opencode-specific failure modes",
+      "priority": "P2",
+      "tddPhase": "review",
+      "verificationCriteria": "Ralph Loop works reliably for both modes, no Claude regressions, clear documentation of opencode limitations",
+      "reviewChecklist": ["Silence detection reliability", "No Claude regressions in Ralph", "Circuit breaker handles opencode failures", "Task queue mode-agnostic"],
+      "pairedWith": "P2-008",
+      "dependencies": ["P2-008"]
+    },
+    {
+      "id": "P2-010",
+      "content": "Final typecheck and comprehensive review — run tsc --noEmit across entire project, verify all new files follow import conventions (utils from ./utils, types via type imports), verify no unused imports/variables (noUnusedLocals/noUnusedParameters), run existing test files individually to confirm no regressions, update CLAUDE.md with opencode session documentation",
+      "priority": "P2",
+      "tddPhase": "review",
+      "verificationCriteria": "tsc --noEmit passes with zero errors, existing tests pass, CLAUDE.md updated with opencode section",
+      "reviewChecklist": ["tsc --noEmit clean", "Import conventions followed", "No unused variables", "Existing tests pass", "CLAUDE.md updated", "No TODO/FIXME left unaddressed"],
+      "dependencies": ["P2-003", "P2-006", "P2-009"]
+    }
+  ],
+  "gaps": [
+    "OpenCode binary not currently installed on this machine — manual installation required before integration testing",
+    "OpenCode's exact TUI escape sequence behavior with xterm.js is unknown — may need rendering fixes",
+    "OpenCode's signal handling (SIGWINCH for resize, SIGTERM for graceful shutdown) needs empirical testing",
+    "OpenCode's stdin behavior for pasted/programmatic text input is unverified — writeViaMux may need adaptation",
+    "Token/cost tracking for opencode sessions is deferred — no structured way to get this from TUI output",
+    "OpenCode's 'opencode serve' API integration (Strategy B) is not included in this plan — it's a separate follow-up project",
+    "OpenCode was archived in September 2025 and moved to 'Crush' — long-term maintenance risk",
+    "Multi-line input compatibility with OpenCode's TUI is unknown (Claudeman sends single-line via writeViaMux)",
+    "AI idle checker prompt needs OpenCode-specific variant if AI-based idle detection is desired later",
+    "Agent Teams integration with OpenCode sessions is not covered — teams are Claude Code-specific"
+  ],
+  "warnings": [
+    "OpenCode's GitHub repository was archived (Sep 2025) and the project moved to 'Crush' — consider whether to target opencode or crush",
+    "Silence-based idle detection is less precise than Claude's prompt marker detection — may cause false positives (TUI animation) or false negatives (long-running quiet operations)",
+    "The respawn controller's AI idle checker uses a Claude-specific prompt — it will be disabled for opencode, reducing idle detection reliability",
+    "OpenCode's Bubble Tea TUI uses alternate screen buffer which may interact poorly with xterm.js buffer capture",
+    "API key passthrough in tmux env exports means keys appear in tmux's process tree — security consideration for shared machines",
+    "opencode.json in the project root may conflict with Claudeman's CLI flag overrides — need clear precedence documentation",
+    "Ralph Loop with opencode may be less reliable without completion phrase detection — silence-based detection has higher error margin",
+    "Test port allocation: this plan uses ports 3161-3165 — verify no conflicts with existing tests before implementation"
+  ]
+}

skills-lock.json

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "skills": {
+    "remotion-best-practices": {
+      "source": "remotion-dev/skills",
+      "sourceType": "github",
+      "computedHash": "9851afb52e1b892c43b2af973bda1776ce01fedfdfe704e0cfd70069a3a9c300"
+    }
+  }
+}

src/config/buffer-limits.ts

@@ -85,3 +85,26 @@ export const MAX_RESPAWN_BUFFER_SIZE = 1 * 1024 * 1024; // 1MB
  * Size to trim respawn buffer to when max is exceeded.
  */
 export const TRIM_RESPAWN_BUFFER_TO = 512 * 1024; // 512KB
+
+// ============================================================================
+// Run Summary Limits
+// ============================================================================
+
+/**
+ * Maximum number of events to keep in run summary.
+ */
+export const MAX_RUN_SUMMARY_EVENTS = 1000;
+
+/**
+ * Number of events to keep when trimming run summary.
+ */
+export const TRIM_RUN_SUMMARY_TO = 800;
+
+// ============================================================================
+// Spawn Message Limits
+// ============================================================================
+
+/**
+ * Maximum messages per spawn communication channel.
+ */
+export const MAX_MESSAGES_PER_CHANNEL = 100;

src/config/map-limits.ts

@@ -14,6 +14,28 @@
  * @module config/map-limits
  */
 
+// ============================================================================
+// Agent Tracking Limits
+// ============================================================================
+
+/**
+ * Maximum number of agents to track across all sessions.
+ * Oldest agents are evicted when limit is exceeded (LRU policy).
+ */
+export const MAX_TRACKED_AGENTS = 500;
+
+/**
+ * Maximum activity entries to keep per agent.
+ * Includes tool calls, status updates, progress reports.
+ */
+export const MAX_SUBAGENT_ACTIVITY_PER_AGENT = 100;
+
+/**
+ * Maximum tool results to keep per agent.
+ * Prevents memory growth from long-running agents with many tool calls.
+ */
+export const MAX_TOOL_RESULTS_PER_AGENT = 200;
+
 // ============================================================================
 // Session Tracking Limits
 // ============================================================================
@@ -43,6 +65,11 @@ export const MAX_SSE_CLIENTS = 100;
  */
 export const MAX_TODOS_PER_SESSION = 500;
 
+/**
+ * TTL for completed todo items before cleanup (1 hour).
+ */
+export const COMPLETED_TODO_TTL_MS = 60 * 60 * 1000;
+
 // ============================================================================
 // Pending Tool Calls Limits
 // ============================================================================

src/file-stream-manager.ts

@@ -398,7 +398,13 @@ export class FileStreamManager extends EventEmitter {
 
     // Check if the resolved path is within the working directory
     // or common log directories (/tmp intentionally excluded — world-writable)
-    const allowedPaths = [normalizedWorkingDir, '/var/log', resolve(homedir(), 'logs')];
+    const allowedPaths = [
+      normalizedWorkingDir,
+      '/var/log',
+      resolve(homedir(), '.local/share'),
+      resolve(homedir(), '.cache'),
+      resolve(homedir(), 'logs'),
+    ];
 
     const isAllowed = allowedPaths.some((allowed) => {
       const rel = relative(allowed, absolutePath);

src/hooks-config.ts

@@ -27,10 +27,9 @@ export function generateHooksConfig(): { hooks: Record<string, unknown[]> } {
   // Falls back to empty object if stdin is unavailable or malformed.
   const curlCmd = (event: HookEventType) =>
     `HOOK_DATA=$(cat 2>/dev/null || echo '{}'); ` +
-    `printf '{"event":"${event}","sessionId":"%s","data":%s}' "$CODEMAN_SESSION_ID" "$HOOK_DATA" | ` +
     `curl -s -X POST "$CODEMAN_API_URL/api/hook-event" ` +
     `-H 'Content-Type: application/json' ` +
-    `--data @- ` +
+    `-d "{\\"event\\":\\"${event}\\",\\"sessionId\\":\\"$CODEMAN_SESSION_ID\\",\\"data\\":$HOOK_DATA}" ` +
     `2>/dev/null || true`;
 
   return {

src/plan-orchestrator.ts

@@ -79,6 +79,12 @@ export interface ResearchResult {
   durationMs: number;
 }
 
+export interface PlannerResult {
+  items: PlanItem[];
+  gaps: string[];
+  warnings: string[];
+}
+
 export interface DetailedPlanResult {
   success: boolean;
   items?: PlanItem[];
@@ -438,6 +444,8 @@ export class PlanOrchestrator {
     try {
       const { result: response } = await session.runPrompt(prompt, { model: this.researchModel });
 
+      this.runningSessions.delete(session);
+
       const durationMs = Date.now() - startTime;
 
       // Extract JSON from response
@@ -520,6 +528,7 @@ export class PlanOrchestrator {
 
       return result;
     } catch (err) {
+      this.runningSessions.delete(session);
       const durationMs = Date.now() - startTime;
       const error = err instanceof Error ? err.message : String(err);
       onSubagent?.({
@@ -545,10 +554,7 @@ export class PlanOrchestrator {
         durationMs,
       };
     } finally {
-      // Always clean up session and progress interval — centralizing here
-      // prevents the race where cancel() and catch both try to manage the set
-      await session.stop().catch(() => {});
-      this.runningSessions.delete(session);
+      // Always clear the progress interval to prevent memory leaks
       clearInterval(progressInterval);
     }
   }
@@ -611,6 +617,8 @@ export class PlanOrchestrator {
     try {
       const { result: response } = await session.runPrompt(prompt, { model: this.plannerModel });
 
+      this.runningSessions.delete(session);
+
       const durationMs = Date.now() - startTime;
 
       // Extract JSON from response
@@ -662,6 +670,7 @@ export class PlanOrchestrator {
 
       return { success: true, items, gaps, warnings };
     } catch (err) {
+      this.runningSessions.delete(session);
       const durationMs = Date.now() - startTime;
       const error = err instanceof Error ? err.message : String(err);
       onSubagent?.({
@@ -675,10 +684,7 @@ export class PlanOrchestrator {
       });
       return { success: false, error };
     } finally {
-      // Always clean up session and progress interval — centralizing here
-      // prevents the race where cancel() and catch both try to manage the set
-      await session.stop().catch(() => {});
-      this.runningSessions.delete(session);
+      // Always clear the progress interval to prevent memory leaks
       clearInterval(progressInterval);
     }
   }

src/ralph-loop.ts

@@ -77,7 +77,6 @@ export class RalphLoop extends EventEmitter {
     completion: (sessionId: string, phrase: string) => void;
     error: (sessionId: string, error: string) => void;
     stopped: (sessionId: string) => void;
-    taskError: (sessionId: string, taskId: string, error: string) => void;
   } | null = null;
 
   constructor(options: RalphLoopOptions = {}) {
@@ -119,15 +118,11 @@ export class RalphLoop extends EventEmitter {
       stopped: (sessionId: string) => {
         this.handleSessionStopped(sessionId);
       },
-      taskError: (sessionId: string, taskId: string, error: string) => {
-        this.handleSessionTaskError(sessionId, taskId, error);
-      },
     };
 
     this.sessionManager.on('sessionCompletion', this.sessionEventHandlers.completion);
     this.sessionManager.on('sessionError', this.sessionEventHandlers.error);
     this.sessionManager.on('sessionStopped', this.sessionEventHandlers.stopped);
-    this.sessionManager.on('sessionTaskError', this.sessionEventHandlers.taskError);
   }
 
   /** Remove event listeners to prevent memory leaks */
@@ -136,7 +131,6 @@ export class RalphLoop extends EventEmitter {
       this.sessionManager.off('sessionCompletion', this.sessionEventHandlers.completion);
       this.sessionManager.off('sessionError', this.sessionEventHandlers.error);
       this.sessionManager.off('sessionStopped', this.sessionEventHandlers.stopped);
-      this.sessionManager.off('sessionTaskError', this.sessionEventHandlers.taskError);
       this.sessionEventHandlers = null;
     }
   }
@@ -287,11 +281,8 @@ export class RalphLoop extends EventEmitter {
   private async tick(): Promise<void> {
     this.store.setRalphLoopState({ lastCheckAt: Date.now() });
 
-    // Run sequentially: timeouts first so timed-out tasks are cleaned up
-    // before assignTasks() picks new work (prevents race where both
-    // mutate the same task concurrently)
-    await this.checkTimeouts();
-    await this.assignTasks();
+    // Run independent checks in parallel for better performance
+    await Promise.all([this.checkTimeouts(), this.assignTasks()]);
 
     // Check if we should auto-generate tasks (depends on assignment results)
     if (this.autoGenerateTasks && this.shouldGenerateTasks()) {
@@ -313,11 +304,7 @@ export class RalphLoop extends EventEmitter {
         break;
       }
 
-      try {
-        await this.assignTaskToSession(task, session);
-      } catch (err) {
-        console.error(`[RalphLoop] Failed to assign task ${task.id} to session ${session.id}:`, err);
-      }
+      await this.assignTaskToSession(task, session);
     }
   }
 
@@ -413,17 +400,6 @@ export class RalphLoop extends EventEmitter {
     }
   }
 
-  private handleSessionTaskError(_sessionId: string, taskId: string, error: string): void {
-    const task = this.taskQueue.getTask(taskId);
-    if (!task) {
-      return;
-    }
-
-    task.fail(error);
-    this.taskQueue.updateTask(task);
-    this.emit('taskFailed', task.id, error);
-  }
-
   private shouldGenerateTasks(): boolean {
     // Generate tasks if:
     // 1. No pending tasks
@@ -509,7 +485,7 @@ export function getRalphLoop(options?: RalphLoopOptions): RalphLoop {
 }
 
 /** Destroys the singleton instance. Use in tests or for cleanup. */
-function destroyRalphLoop(): void {
+export function destroyRalphLoop(): void {
   if (loopInstance) {
     loopInstance.destroy();
     loopInstance = null;

src/respawn-controller.ts

@@ -641,6 +641,9 @@ export class RespawnController extends EventEmitter {
   /** Current state machine state */
   private _state: RespawnState = 'stopped';
 
+  /** Timer for idle detection timeout */
+  private idleTimer: NodeJS.Timeout | null = null;
+
   /** Timer for step delays */
   private stepTimer: NodeJS.Timeout | null = null;
 
@@ -653,9 +656,6 @@ export class RespawnController extends EventEmitter {
   /** Timer for periodic detection status updates */
   private detectionUpdateTimer: NodeJS.Timeout | null = null;
 
-  /** Cached key fields from last emitted detection status (for dedup) */
-  private lastEmittedDetectionKey: string = '';
-
   /** Timer for auto-accepting plan mode prompts */
   private autoAcceptTimer: NodeJS.Timeout | null = null;
 
@@ -1199,18 +1199,10 @@ export class RespawnController extends EventEmitter {
   private startDetectionUpdates(): void {
     this.stopDetectionUpdates();
     if (this._state === 'stopped') return;
-    this.lastEmittedDetectionKey = '';
     this.detectionUpdateTimer = setInterval(() => {
       try {
         if (this._state !== 'stopped') {
-          const status = this.getDetectionStatus();
-          // Only emit when status meaningfully changed (confidence, state text, or timer values)
-          // to avoid broadcasting identical data every 2s for stable/idle sessions.
-          const key = `${status.confidenceLevel}|${status.statusText}|${this._state}`;
-          if (key !== this.lastEmittedDetectionKey) {
-            this.lastEmittedDetectionKey = key;
-            this.emit('detectionUpdate', status);
-          }
+          this.emit('detectionUpdate', this.getDetectionStatus());
         }
       } catch (err) {
         console.error(`[RespawnController] Error in detectionUpdateTimer:`, err);
@@ -1513,6 +1505,7 @@ export class RespawnController extends EventEmitter {
       this.elicitationDetected = false; // Clear on new work cycle
       this.resetHookState(); // Clear hook signals on new work
       this.lastWorkingPatternTime = now;
+      this.clearIdleTimer();
 
       // Cancel hook confirmation timer if running
       this.cancelTrackedTimer('hook-confirm', this.hookConfirmTimer, 'working patterns detected');
@@ -1615,6 +1608,7 @@ export class RespawnController extends EventEmitter {
    * @fires stepCompleted - With step 'update'
    */
   private checkUpdateComplete(): void {
+    this.clearIdleTimer();
     this.log('Update completed (ready indicator)');
     this.emit('stepCompleted', 'update');
 
@@ -1649,6 +1643,7 @@ export class RespawnController extends EventEmitter {
    * @fires stepCompleted - With step 'clear'
    */
   private checkClearComplete(): void {
+    this.clearIdleTimer();
     // Clear the fallback timer since we got prompt detection
     this.cancelTrackedTimer('clear-fallback', this.clearFallbackTimer, 'prompt detected');
     this.clearFallbackTimer = null;
@@ -1672,6 +1667,7 @@ export class RespawnController extends EventEmitter {
    * @fires stepCompleted - With step 'init' (if no kickstart)
    */
   private checkInitComplete(): void {
+    this.clearIdleTimer();
     this.log('/init completed (ready indicator)');
 
     // P2-004: Record step completion
@@ -1719,6 +1715,7 @@ export class RespawnController extends EventEmitter {
    * @fires stepCompleted - With step 'init'
    */
   private checkMonitoringInitIdle(): void {
+    this.clearIdleTimer();
     if (this.stepTimer) {
       clearTimeout(this.stepTimer);
       this.stepTimer = null;
@@ -1760,6 +1757,7 @@ export class RespawnController extends EventEmitter {
    * @fires stepCompleted - With step 'kickstart'
    */
   private checkKickstartComplete(): void {
+    this.clearIdleTimer();
     this.log('Kickstart completed (ready indicator)');
     this.emit('stepCompleted', 'kickstart');
 
@@ -1769,10 +1767,22 @@ export class RespawnController extends EventEmitter {
     this.completeCycle();
   }
 
-  /** Clear all timers (step, completion confirm, no-output, pre-filter, step confirm, auto-accept, hook confirm, and clear fallback) */
+  // Note: Legacy startIdleTimer removed - now using completion-based detection
+  // with startCompletionConfirmTimer() and startNoOutputTimer() instead.
+
+  /** Clear the idle detection timer if running (legacy cleanup) */
+  private clearIdleTimer(): void {
+    if (this.idleTimer) {
+      clearTimeout(this.idleTimer);
+      this.idleTimer = null;
+    }
+  }
+
+  /** Clear all timers (idle, step, completion confirm, no-output, pre-filter, step confirm, auto-accept, hook confirm, and clear fallback) */
   private clearTimers(): void {
     // Clear tracked timers map first to avoid stale entries during individual cleanup
     this.activeTimers.clear();
+    this.clearIdleTimer();
     if (this.stepTimer) {
       clearTimeout(this.stepTimer);
       this.stepTimer = null;

src/session-manager.ts

@@ -54,7 +54,6 @@ interface SessionHandlers {
   error: (data: string) => void;
   completion: (phrase: string) => void;
   exit: () => void;
-  taskError: (taskId: string, error: string) => void;
 }
 
 export class SessionManager extends EventEmitter {
@@ -135,16 +134,12 @@ export class SessionManager extends EventEmitter {
           this.emit('sessionStopped', session.id);
           this.updateSessionState(session);
         },
-        taskError: (taskId: string, error: string) => {
-          this.emit('sessionTaskError', session.id, taskId, error);
-        },
       };
 
       session.on('output', handlers.output);
       session.on('error', handlers.error);
       session.on('completion', handlers.completion);
       session.on('exit', handlers.exit);
-      session.on('taskError', handlers.taskError);
 
       // Store handlers for later cleanup
       this.sessionHandlers.set(session.id, handlers);
@@ -188,7 +183,6 @@ export class SessionManager extends EventEmitter {
       session.off('error', handlers.error);
       session.off('completion', handlers.completion);
       session.off('exit', handlers.exit);
-      session.off('taskError', handlers.taskError);
       this.sessionHandlers.delete(id);
     }
 

src/session.ts

@@ -49,6 +49,7 @@ import {
 
 export type { BackgroundTask } from './task-tracker.js';
 export type { RalphTrackerState, RalphTodoItem, ActiveBashTool } from './types.js';
+export { withTimeout };
 
 /** Line buffer flush interval (100ms) - forces processing of partial lines */
 const LINE_BUFFER_FLUSH_INTERVAL = 100;
@@ -96,6 +97,29 @@ const NEWLINE_SPLIT_PATTERN = /\r?\n/;
 // Claude CLI PATH resolution — shared utility
 import { getAugmentedPath } from './utils/claude-cli-resolver.js';
 
+/**
+ * Wraps a promise with a timeout to prevent indefinite hangs.
+ * If the promise doesn't resolve within the timeout, rejects with TimeoutError.
+ *
+ * @param promise - The promise to wrap
+ * @param timeoutMs - Timeout in milliseconds
+ * @param operation - Description of the operation for error messages
+ * @returns Promise that resolves/rejects with the original result or timeout error
+ */
+function withTimeout<T>(promise: Promise<T>, timeoutMs: number, operation: string): Promise<T> {
+  let timeoutId: NodeJS.Timeout;
+
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timeoutId = setTimeout(() => {
+      reject(new Error(`${operation} timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+
+  return Promise.race([promise, timeoutPromise]).finally(() => {
+    clearTimeout(timeoutId);
+  });
+}
+
 /**
  * Represents a JSON message from Claude CLI's stream-json output format.
  * Messages are newline-delimited JSON objects parsed from PTY output.
@@ -2179,16 +2203,6 @@ export class Session extends EventEmitter {
     this._lastActivityAt = Date.now();
     this.runPrompt(input).catch((err) => {
       const errorMsg = err instanceof Error ? err.message : String(err);
-      // Clean up task state so the task queue doesn't get stuck
-      if (this._currentTaskId) {
-        const taskId = this._currentTaskId;
-        this._currentTaskId = null;
-        this._status = 'idle';
-        this._lastActivityAt = Date.now();
-        this.emit('taskError', taskId, errorMsg);
-      } else {
-        this._status = 'idle';
-      }
       this.emit('error', errorMsg);
     });
   }

src/state-store.ts

@@ -62,8 +62,6 @@ export class StateStore {
   private filePath: string;
   private saveTimeout: NodeJS.Timeout | null = null;
   private dirty: boolean = false;
-  private dirtySessions = new Set<string>();
-  private cachedSessionJsons = new Map<string, string>();
 
   // Inner state storage (separate from main state to reduce write frequency)
   private ralphStates: Map<string, RalphSessionState> = new Map();
@@ -99,10 +97,6 @@ export class StateStore {
     this.ralphStatePath = this.filePath.replace('.json', '-inner.json');
     this.state = this.load();
     this.state.config.stateFilePath = this.filePath;
-    // Pre-populate session cache for loaded state
-    for (const [id, session] of Object.entries(this.state.sessions)) {
-      this.cachedSessionJsons.set(id, JSON.stringify(session));
-    }
     this.loadRalphStates();
   }
 
@@ -182,65 +176,6 @@ export class StateStore {
     }
   }
 
-  /**
-   * Assemble JSON string with incremental per-session caching.
-   * Only dirty sessions are re-serialized; clean sessions use cached JSON fragments.
-   */
-  private assembleStateJson(): string {
-    // Re-serialize dirty sessions and update cache
-    for (const id of this.dirtySessions) {
-      const session = this.state.sessions[id];
-      if (session) {
-        this.cachedSessionJsons.set(id, JSON.stringify(session));
-      } else {
-        this.cachedSessionJsons.delete(id);
-      }
-    }
-    this.dirtySessions.clear();
-
-    // Build sessions object from cached fragments
-    const sessionParts: string[] = [];
-    for (const [id, session] of Object.entries(this.state.sessions)) {
-      let json = this.cachedSessionJsons.get(id);
-      if (!json) {
-        // Session not in cache (loaded from disk or set via direct state mutation)
-        json = JSON.stringify(session);
-        this.cachedSessionJsons.set(id, json);
-      }
-      sessionParts.push(`${JSON.stringify(id)}:${json}`);
-    }
-
-    // Prune stale cache entries (sessions removed via direct state mutation)
-    if (this.cachedSessionJsons.size > Object.keys(this.state.sessions).length) {
-      for (const cachedId of this.cachedSessionJsons.keys()) {
-        if (!(cachedId in this.state.sessions)) {
-          this.cachedSessionJsons.delete(cachedId);
-        }
-      }
-    }
-
-    // Build final JSON: sessions from cache, everything else re-serialized (tiny)
-    const sessionsJson = `{${sessionParts.join(',')}}`;
-
-    // Serialize non-session fields individually (they're small)
-    const parts: string[] = [
-      `"sessions":${sessionsJson}`,
-      `"tasks":${JSON.stringify(this.state.tasks)}`,
-      `"ralphLoop":${JSON.stringify(this.state.ralphLoop)}`,
-      `"config":${JSON.stringify(this.state.config)}`,
-    ];
-
-    // Optional fields
-    if (this.state.globalStats) {
-      parts.push(`"globalStats":${JSON.stringify(this.state.globalStats)}`);
-    }
-    if (this.state.tokenStats) {
-      parts.push(`"tokenStats":${JSON.stringify(this.state.tokenStats)}`);
-    }
-
-    return `{${parts.join(',')}}`;
-  }
-
   private async _doSaveAsync(): Promise<void> {
     if (this.saveTimeout) {
       clearTimeout(this.saveTimeout);
@@ -264,29 +199,17 @@ export class StateStore {
 
     // Step 1: Serialize state (validates it's JSON-safe)
     try {
-      json = this.assembleStateJson();
-    } catch (assembleErr) {
-      // Fallback to full serialization if incremental assembly fails
-      console.warn('[StateStore] assembleStateJson failed, falling back to full serialize:', assembleErr);
-      this.cachedSessionJsons.clear();
-      this.dirtySessions.clear();
-      try {
-        json = JSON.stringify(this.state);
-      } catch (err) {
-        console.error('[StateStore] Failed to serialize state (circular reference or invalid data):', err);
-        this.consecutiveSaveFailures++;
-        if (this.consecutiveSaveFailures >= MAX_CONSECUTIVE_FAILURES) {
-          console.error('[StateStore] Circuit breaker OPEN - serialization failing repeatedly');
-          this.circuitBreakerOpen = true;
-        }
-        return;
+      json = JSON.stringify(this.state);
+    } catch (err) {
+      console.error('[StateStore] Failed to serialize state (circular reference or invalid data):', err);
+      this.consecutiveSaveFailures++;
+      if (this.consecutiveSaveFailures >= MAX_CONSECUTIVE_FAILURES) {
+        console.error('[StateStore] Circuit breaker OPEN - serialization failing repeatedly');
+        this.circuitBreakerOpen = true;
       }
+      return;
     }
 
-    // Clear dirty flag BEFORE async I/O so mutations during write re-set it.
-    // The state snapshot is already captured in `json` above.
-    this.dirty = false;
-
     // Step 2: Create backup via file copy (async, no read+parse+write)
     try {
       await access(this.filePath);
@@ -300,6 +223,8 @@ export class StateStore {
       await writeFile(tempPath, json, 'utf-8');
       await rename(tempPath, this.filePath);
 
+      // Success! Clear dirty flag AFTER write completes
+      this.dirty = false;
       this.consecutiveSaveFailures = 0;
       if (this.circuitBreakerOpen) {
         console.log('[StateStore] Circuit breaker CLOSED - save succeeded');
@@ -307,8 +232,6 @@ export class StateStore {
       }
     } catch (err) {
       console.error('[StateStore] Failed to write state file:', err);
-      // Re-mark dirty so the data is retried on the next save cycle
-      this.dirty = true;
       this.consecutiveSaveFailures++;
 
       // Try to clean up temp file on error
@@ -352,23 +275,15 @@ export class StateStore {
     let json: string;
 
     try {
-      json = this.assembleStateJson();
-    } catch (assembleErr) {
-      // Fallback to full serialization if incremental assembly fails
-      console.warn('[StateStore] assembleStateJson failed, falling back to full serialize:', assembleErr);
-      this.cachedSessionJsons.clear();
-      this.dirtySessions.clear();
-      try {
-        json = JSON.stringify(this.state);
-      } catch (err) {
-        console.error('[StateStore] Failed to serialize state (circular reference or invalid data):', err);
-        this.consecutiveSaveFailures++;
-        if (this.consecutiveSaveFailures >= MAX_CONSECUTIVE_FAILURES) {
-          console.error('[StateStore] Circuit breaker OPEN - serialization failing repeatedly');
-          this.circuitBreakerOpen = true;
-        }
-        return;
+      json = JSON.stringify(this.state);
+    } catch (err) {
+      console.error('[StateStore] Failed to serialize state (circular reference or invalid data):', err);
+      this.consecutiveSaveFailures++;
+      if (this.consecutiveSaveFailures >= MAX_CONSECUTIVE_FAILURES) {
+        console.error('[StateStore] Circuit breaker OPEN - serialization failing repeatedly');
+        this.circuitBreakerOpen = true;
       }
+      return;
     }
 
     // Backup via atomic copy (avoids reading entire file into memory)
@@ -468,15 +383,12 @@ export class StateStore {
   /** Sets a session state and triggers a debounced save. */
   setSession(id: string, session: AppState['sessions'][string]) {
     this.state.sessions[id] = session;
-    this.dirtySessions.add(id);
     this.save();
   }
 
   /** Removes a session state and triggers a debounced save. */
   removeSession(id: string) {
     delete this.state.sessions[id];
-    this.cachedSessionJsons.delete(id);
-    this.dirtySessions.delete(id);
     this.save();
   }
 
@@ -497,8 +409,6 @@ export class StateStore {
         const name = this.state.sessions[sessionId]?.name;
         cleaned.push({ id: sessionId, name });
         delete this.state.sessions[sessionId];
-        this.cachedSessionJsons.delete(sessionId);
-        this.dirtySessions.delete(sessionId);
         // Also clean up Ralph state for this session
         this.ralphStates.delete(sessionId);
       }
@@ -561,8 +471,6 @@ export class StateStore {
     this.state = createInitialState();
     this.state.config.stateFilePath = this.filePath;
     this.ralphStates.clear();
-    this.cachedSessionJsons.clear();
-    this.dirtySessions.clear();
     this.saveNow(); // Immediate save for reset operations
     this.saveRalphStatesNow();
   }

src/subagent-watcher.ts

@@ -160,9 +160,8 @@ const FILE_CONTENT_DEBOUNCE_MS = 100; // Debounce delay for file content updates
 
 export class SubagentWatcher extends EventEmitter {
   private filePositions = new Map<string, number>();
+  private fileWatchers = new Map<string, FSWatcher>();
   private dirWatchers = new Map<string, FSWatcher>();
-  // Per-file debounce timers for directory watcher (replaces per-file FSWatchers)
-  private fileDebouncers = new Map<string, NodeJS.Timeout>();
   private agentInfo = new Map<string, SubagentInfo>();
   private idleTimers = new Map<string, NodeJS.Timeout>();
   private pollInterval: NodeJS.Timeout | null = null;
@@ -181,8 +180,7 @@ export class SubagentWatcher extends EventEmitter {
   private parentDescriptionCache = new Map<string, { descriptions: Map<string, string>; timestamp: number }>();
   // Store error handlers for FSWatchers to enable proper cleanup (prevent memory leaks)
   private dirWatcherErrorHandlers = new Map<string, (error: Error) => void>();
-  // Map filePath → { projectHash, sessionId } for directory watcher file-change handling
-  private fileAgentContext = new Map<string, { projectHash: string; sessionId: string }>();
+  private fileWatcherErrorHandlers = new Map<string, (error: Error) => void>();
 
   constructor() {
     super();
@@ -428,12 +426,17 @@ export class SubagentWatcher extends EventEmitter {
       this.livenessInterval = null;
     }
 
-    // Clear file debouncers
-    for (const timer of this.fileDebouncers.values()) {
-      clearTimeout(timer);
+    // Remove error handlers before closing watchers to prevent memory leak
+    for (const [filePath, handler] of this.fileWatcherErrorHandlers) {
+      const watcher = this.fileWatchers.get(filePath);
+      if (watcher) watcher.off('error', handler);
     }
-    this.fileDebouncers.clear();
-    this.fileAgentContext.clear();
+    this.fileWatcherErrorHandlers.clear();
+
+    for (const watcher of this.fileWatchers.values()) {
+      watcher.close();
+    }
+    this.fileWatchers.clear();
 
     // Remove error handlers before closing watchers to prevent memory leak
     for (const [dir, handler] of this.dirWatcherErrorHandlers) {
@@ -531,11 +534,11 @@ export class SubagentWatcher extends EventEmitter {
       this.agentInfo.delete(agentId);
       this.pendingToolCalls.delete(agentId);
       this.filePositions.delete(info.filePath);
-      this.fileAgentContext.delete(info.filePath);
-      const debounceTimer = this.fileDebouncers.get(info.filePath);
-      if (debounceTimer) {
-        clearTimeout(debounceTimer);
-        this.fileDebouncers.delete(info.filePath);
+      const watcher = this.fileWatchers.get(info.filePath);
+      if (watcher) {
+        watcher.close();
+        this.fileWatchers.delete(info.filePath);
+        this.fileWatcherErrorHandlers.delete(info.filePath);
       }
       const timer = this.idleTimers.get(agentId);
       if (timer) {
@@ -619,7 +622,7 @@ export class SubagentWatcher extends EventEmitter {
    */
   getStats(): {
     agentCount: number;
-    fileDebouncerCount: number;
+    fileWatcherCount: number;
     dirWatcherCount: number;
     idleTimerCount: number;
     pendingToolCallsCount: number;
@@ -634,7 +637,7 @@ export class SubagentWatcher extends EventEmitter {
 
     return {
       agentCount: this.agentInfo.size,
-      fileDebouncerCount: this.fileDebouncers.size,
+      fileWatcherCount: this.fileWatchers.size,
       dirWatcherCount: this.dirWatchers.size,
       idleTimerCount: this.idleTimers.size,
       pendingToolCallsCount,
@@ -952,29 +955,14 @@ export class SubagentWatcher extends EventEmitter {
     try {
       // The parent session's transcript is at: ~/.claude/projects/{projectHash}/{sessionId}.jsonl
       const transcriptPath = join(CLAUDE_PROJECTS_DIR, projectHash, `${sessionId}.jsonl`);
-      let fileSize: number;
       try {
-        const fileStat = await statAsync(transcriptPath);
-        fileSize = fileStat.size;
+        await statAsync(transcriptPath);
       } catch {
         return undefined;
       }
 
-      // Only read last 16KB — toolUseResult entries are near the end of the transcript
-      const TAIL_BYTES = 16384;
-      const startOffset = Math.max(0, fileSize - TAIL_BYTES);
-      const content = await new Promise<string>((resolve, reject) => {
-        const chunks: string[] = [];
-        const stream = createReadStream(transcriptPath, { start: startOffset, encoding: 'utf8' });
-        stream.on('data', (chunk) => chunks.push(String(chunk)));
-        stream.on('end', () => resolve(chunks.join('')));
-        stream.on('error', reject);
-      });
-      let lines = content.split('\n').filter((l) => l.trim());
-      // If we started mid-file, drop the first partial line
-      if (startOffset > 0 && lines.length > 0) {
-        lines = lines.slice(1);
-      }
+      const content = await readFile(transcriptPath, 'utf8');
+      const lines = content.split('\n').filter((l) => l.trim());
 
       // Parse ALL toolUseResult entries into a Map and cache them
       const descriptions = new Map<string, string>();
@@ -1103,51 +1091,39 @@ export class SubagentWatcher extends EventEmitter {
   }
 
   /**
-   * Watch a subagent directory for new and changed files.
-   * Uses a single directory-level fs.watch() instead of per-file watchers.
-   * On Linux, inotify IN_MODIFY fires for content changes within the directory.
+   * Watch a subagent directory for new/updated files
    */
   private async watchSubagentDir(dir: string, projectHash: string, sessionId: string): Promise<void> {
     if (this.knownSubagentDirs.has(dir)) return;
     this.knownSubagentDirs.add(dir);
 
-    // Register existing files (initial scan - skip old files)
+    // Watch existing files (initial scan - skip old files)
     try {
       const files = await readdir(dir);
       for (const file of files) {
         if (file.endsWith('.jsonl')) {
-          await this.registerAgentFile(join(dir, file), projectHash, sessionId, true);
+          await this.watchAgentFile(join(dir, file), projectHash, sessionId, true);
         }
       }
     } catch {
       return;
     }
 
-    // Single directory watcher handles both new files and file content changes
+    // Watch for new files with debounce to allow content to be written
     try {
       const watcher = watch(dir, (_eventType, filename) => {
-        if (!filename?.endsWith('.jsonl')) return;
-        const filePath = join(dir, filename);
-
-        // Clear existing debounce for this file
-        const existing = this.fileDebouncers.get(filePath);
-        if (existing) clearTimeout(existing);
-
-        // Debounce 100ms to batch rapid writes
-        const timer = setTimeout(() => {
-          this.fileDebouncers.delete(filePath);
-          if (!existsSync(filePath)) return;
-
-          if (this.fileAgentContext.has(filePath)) {
-            // Known file — handle content change
-            this.handleFileChange(filePath).catch(() => {});
-          } else {
-            // New file — register it
-            this.registerAgentFile(filePath, projectHash, sessionId).catch(() => {});
-          }
-        }, FILE_CONTENT_DEBOUNCE_MS);
-
-        this.fileDebouncers.set(filePath, timer);
+        if (filename?.endsWith('.jsonl')) {
+          const filePath = join(dir, filename);
+          // Wait 100ms for file content to be written before processing
+          // Even if file is empty after debounce, we still watch it - the
+          // description retry mechanisms in processEntry and the file change
+          // handler will extract description when content arrives
+          setTimeout(() => {
+            if (existsSync(filePath)) {
+              this.watchAgentFile(filePath, projectHash, sessionId);
+            }
+          }, FILE_CONTENT_DEBOUNCE_MS);
+        }
       });
 
       // Handle watcher errors to prevent unhandled exceptions
@@ -1169,80 +1145,26 @@ export class SubagentWatcher extends EventEmitter {
   }
 
   /**
-   * Handle a file content change for an already-registered agent file.
-   * Tails from last known position, updates info, retries description if missing.
-   */
-  private async handleFileChange(filePath: string): Promise<void> {
-    const context = this.fileAgentContext.get(filePath);
-    if (!context) return;
-
-    const agentId = basename(filePath).replace('agent-', '').replace('.jsonl', '');
-    const currentPos = this.filePositions.get(filePath) || 0;
-    const newPos = await this.tailFile(filePath, agentId, context.sessionId, currentPos);
-    this.filePositions.set(filePath, newPos);
-
-    // Update info
-    const existingInfo = this.agentInfo.get(agentId);
-    if (existingInfo) {
-      try {
-        const newStat = await statAsync(filePath);
-        existingInfo.lastActivityAt = Date.now();
-        existingInfo.fileSize = newStat.size;
-        existingInfo.status = 'active';
-      } catch {
-        // Stat failed
-      }
-
-      // Retry description extraction if missing (race condition fix)
-      if (!existingInfo.description) {
-        // First try parent transcript (most reliable)
-        let extractedDescription = await this.extractDescriptionFromParentTranscript(
-          existingInfo.projectHash,
-          existingInfo.sessionId,
-          agentId
-        );
-        // Fallback to subagent file
-        if (!extractedDescription) {
-          extractedDescription = await this.extractDescriptionFromFile(filePath);
-        }
-        if (extractedDescription) {
-          // Check if this is an internal agent - if so, remove it
-          if (this.isInternalAgent(extractedDescription)) {
-            this.removeAgent(agentId);
-            return;
-          }
-          existingInfo.description = extractedDescription;
-          this.emit('subagent:updated', existingInfo);
-        }
-      }
-
-      // Reset idle timer
-      this.resetIdleTimer(agentId);
-    }
-  }
-
-  /**
-   * Register a specific agent transcript file (discovery + initial read).
-   * Does NOT create a per-file watcher — the directory watcher handles changes.
+   * Watch a specific agent transcript file
    * @param filePath Path to the agent transcript file
    * @param projectHash Claude project hash
    * @param sessionId Claude session ID
    * @param isInitialScan If true, skip files older than STARTUP_MAX_FILE_AGE_MS
    */
-  private async registerAgentFile(
+  private async watchAgentFile(
     filePath: string,
     projectHash: string,
     sessionId: string,
     isInitialScan: boolean = false
   ): Promise<void> {
-    if (this.fileAgentContext.has(filePath)) return;
+    if (this.fileWatchers.has(filePath)) return;
 
     const agentId = basename(filePath).replace('agent-', '').replace('.jsonl', '');
 
     // Initial info - handle race condition where file may be deleted between discovery and stat
-    let fileStat;
+    let stat;
     try {
-      fileStat = await statAsync(filePath);
+      stat = await statAsync(filePath);
     } catch {
       // File was deleted between discovery and stat - skip this agent
       return;
@@ -1250,7 +1172,7 @@ export class SubagentWatcher extends EventEmitter {
 
     // On initial scan, skip old files to avoid loading stale historical data
     if (isInitialScan) {
-      const fileAge = Date.now() - fileStat.mtime.getTime();
+      const fileAge = Date.now() - stat.mtime.getTime();
       if (fileAge > STARTUP_MAX_FILE_AGE_MS) {
         return; // Skip old files on startup
       }
@@ -1275,12 +1197,12 @@ export class SubagentWatcher extends EventEmitter {
       sessionId,
       projectHash,
       filePath,
-      startedAt: fileStat.birthtime.toISOString(),
-      lastActivityAt: fileStat.mtime.getTime(),
+      startedAt: stat.birthtime.toISOString(),
+      lastActivityAt: stat.mtime.getTime(),
       status: 'active',
       toolCallCount: 0,
       entryCount: 0,
-      fileSize: fileStat.size,
+      fileSize: stat.size,
       description,
     };
 
@@ -1299,8 +1221,6 @@ export class SubagentWatcher extends EventEmitter {
       }
     }
 
-    // Track file context for directory watcher change handling
-    this.fileAgentContext.set(filePath, { projectHash, sessionId });
     this.agentInfo.set(agentId, info);
     this.emit('subagent:discovered', info);
 
@@ -1314,7 +1234,71 @@ export class SubagentWatcher extends EventEmitter {
         console.warn(`[SubagentWatcher] Failed to read initial content for ${agentId}:`, err);
       });
 
-    this.resetIdleTimer(agentId);
+    // Watch for changes
+    try {
+      const watcher = watch(filePath, async (eventType) => {
+        if (eventType === 'change') {
+          const currentPos = this.filePositions.get(filePath) || 0;
+          const newPos = await this.tailFile(filePath, agentId, sessionId, currentPos);
+          this.filePositions.set(filePath, newPos);
+
+          // Update info
+          const existingInfo = this.agentInfo.get(agentId);
+          if (existingInfo) {
+            try {
+              const newStat = await statAsync(filePath);
+              existingInfo.lastActivityAt = Date.now();
+              existingInfo.fileSize = newStat.size;
+              existingInfo.status = 'active';
+            } catch {
+              // Stat failed
+            }
+
+            // Retry description extraction if missing (race condition fix)
+            if (!existingInfo.description) {
+              // First try parent transcript (most reliable)
+              let extractedDescription = await this.extractDescriptionFromParentTranscript(
+                existingInfo.projectHash,
+                existingInfo.sessionId,
+                agentId
+              );
+              // Fallback to subagent file
+              if (!extractedDescription) {
+                extractedDescription = await this.extractDescriptionFromFile(filePath);
+              }
+              if (extractedDescription) {
+                // Check if this is an internal agent - if so, remove it
+                if (this.isInternalAgent(extractedDescription)) {
+                  this.removeAgent(agentId);
+                  return;
+                }
+                existingInfo.description = extractedDescription;
+                this.emit('subagent:updated', existingInfo);
+              }
+            }
+
+            // Reset idle timer
+            this.resetIdleTimer(agentId);
+          }
+        }
+      });
+
+      // Handle watcher errors to prevent unhandled exceptions
+      // Store handler reference for proper cleanup
+      const errorHandler = (error: Error) => {
+        this.emit('subagent:error', error instanceof Error ? error : new Error(String(error)), agentId);
+        watcher.close();
+        this.fileWatcherErrorHandlers.delete(filePath);
+        this.fileWatchers.delete(filePath);
+      };
+      watcher.on('error', errorHandler);
+      this.fileWatcherErrorHandlers.set(filePath, errorHandler);
+
+      this.fileWatchers.set(filePath, watcher);
+      this.resetIdleTimer(agentId);
+    } catch {
+      // Watch failed
+    }
   }
 
   /**

src/team-watcher.ts

@@ -13,14 +13,12 @@ import { readdir, readFile, stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
-import { watch as chokidarWatch, type FSWatcher as ChokidarWatcher } from 'chokidar';
-
 import type { TeamConfig, TeamMember, TeamTask, InboxMessage } from './types.js';
 import { LRUMap } from './utils/lru-map.js';
 
 // ========== Constants ==========
 
-const POLL_INTERVAL_MS = 30000;
+const POLL_INTERVAL_MS = 5000;
 const MAX_CACHED_TEAMS = 50;
 const MAX_CACHED_TASKS = 200;
 
@@ -39,8 +37,6 @@ export class TeamWatcher extends EventEmitter {
   private inboxMtimes: Map<string, number> = new Map();
   // Reverse index: sessionId → teamName for O(1) lookup
   private sessionToTeam: Map<string, string> = new Map();
-  private teamsWatcher: ChokidarWatcher | null = null;
-  private tasksWatcher: ChokidarWatcher | null = null;
 
   constructor(teamsDir?: string, tasksDir?: string) {
     super();
@@ -53,60 +49,9 @@ export class TeamWatcher extends EventEmitter {
     if (this.pollTimer) return;
     this.poll();
     this.pollTimer = setInterval(() => this.poll(), POLL_INTERVAL_MS);
-    this.setupFsWatchers();
-  }
-
-  private setupFsWatchers(): void {
-    try {
-      this.teamsWatcher = chokidarWatch(this.teamsDir, {
-        depth: 2,
-        awaitWriteFinish: { stabilityThreshold: 200 },
-        ignored: /\.lock/,
-        ignoreInitial: true,
-        persistent: false,
-      });
-
-      const teamsHandler = () => this.pollAsync().catch(() => {});
-      this.teamsWatcher.on('add', teamsHandler);
-      this.teamsWatcher.on('change', teamsHandler);
-      this.teamsWatcher.on('unlink', teamsHandler);
-      this.teamsWatcher.on('unlinkDir', teamsHandler);
-      this.teamsWatcher.on('error', (err) => {
-        console.warn('[TeamWatcher] chokidar teams watcher error:', err);
-      });
-    } catch (err) {
-      console.warn('[TeamWatcher] Failed to set up teams chokidar watcher, relying on polling:', err);
-    }
-
-    try {
-      this.tasksWatcher = chokidarWatch(this.tasksDir, {
-        depth: 1,
-        awaitWriteFinish: { stabilityThreshold: 200 },
-        ignored: /\.lock/,
-        ignoreInitial: true,
-        persistent: false,
-      });
-
-      this.tasksWatcher.on('add', () => this.pollTasks().catch(() => {}));
-      this.tasksWatcher.on('change', () => this.pollTasks().catch(() => {}));
-      this.tasksWatcher.on('error', (err) => {
-        console.warn('[TeamWatcher] chokidar tasks watcher error:', err);
-      });
-    } catch (err) {
-      console.warn('[TeamWatcher] Failed to set up tasks chokidar watcher, relying on polling:', err);
-    }
   }
 
   stop(): void {
-    // Close chokidar watchers
-    if (this.teamsWatcher) {
-      this.teamsWatcher.close().catch(() => {});
-      this.teamsWatcher = null;
-    }
-    if (this.tasksWatcher) {
-      this.tasksWatcher.close().catch(() => {});
-      this.tasksWatcher = null;
-    }
     if (this.pollTimer) {
       clearInterval(this.pollTimer);
       this.pollTimer = null;

src/types.ts

@@ -667,7 +667,7 @@ export enum ApiErrorCode {
 /**
  * User-friendly error messages for each error code
  */
-const ErrorMessages: Record<ApiErrorCode, string> = {
+export const ErrorMessages: Record<ApiErrorCode, string> = {
   [ApiErrorCode.NOT_FOUND]: 'The requested resource was not found',
   [ApiErrorCode.INVALID_INPUT]: 'Invalid input provided',
   [ApiErrorCode.SESSION_BUSY]: 'Session is currently busy',
@@ -711,6 +711,29 @@ export function createErrorResponse(code: ApiErrorCode, details?: string): ApiRe
   };
 }
 
+/**
+ * Response for session operations
+ */
+export interface SessionResponse {
+  /** Whether the request succeeded */
+  success: boolean;
+  /** Session details if successful (light state — no full buffers) */
+  session?: SessionState & {
+    /** Claude session ID from CLI */
+    claudeSessionId: string | null;
+    /** Total API cost */
+    totalCost: number;
+    /** Number of messages */
+    messageCount: number;
+    /** Whether Claude is working */
+    isWorking: boolean;
+    /** Timestamp of last prompt */
+    lastPromptTime: number;
+  };
+  /** Error message if failed */
+  error?: string;
+}
+
 /**
  * Response for quick start operation
  */

src/utils/index.ts

@@ -15,10 +15,13 @@ export {
   ANSI_ESCAPE_PATTERN_SIMPLE,
   TOKEN_PATTERN,
   SPINNER_PATTERN,
+  createAnsiPatternFull,
+  createAnsiPatternSimple,
+  stripAnsi,
 } from './regex-patterns.js';
-export { MAX_SESSION_TOKENS } from './token-validation.js';
-export { stringSimilarity, fuzzyPhraseMatch, todoContentHash } from './string-similarity.js';
+export { MAX_SESSION_TOKENS, validateTokenCounts, validateTokensAndCost } from './token-validation.js';
+export { stringSimilarity, normalizePhrase, fuzzyPhraseMatch, todoContentHash } from './string-similarity.js';
 export { assertNever } from './type-safety.js';
 export { wrapWithNice } from './nice-wrapper.js';
 export { findClaudeDir, getAugmentedPath } from './claude-cli-resolver.js';
-export { resolveOpenCodeDir, isOpenCodeAvailable } from './opencode-cli-resolver.js';
+export { resolveOpenCodeDir, isOpenCodeAvailable, getOpenCodeAugmentedPath } from './opencode-cli-resolver.js';

src/utils/opencode-cli-resolver.ts

@@ -9,7 +9,7 @@
 
 import { execSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { delimiter, dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 
 /** Timeout for exec commands (5 seconds) */
@@ -71,3 +71,28 @@ export function resolveOpenCodeDir(): string | null {
 export function isOpenCodeAvailable(): boolean {
   return resolveOpenCodeDir() !== null;
 }
+
+/**
+ * Returns a PATH string that includes the directory containing `opencode`.
+ *
+ * Finds the opencode binary (via `which` or common install locations), then
+ * prepends its directory to the current PATH if not already present.
+ * Result is cached for subsequent calls.
+ */
+export function getOpenCodeAugmentedPath(): string {
+  const currentPath = process.env.PATH || '';
+  const dir = resolveOpenCodeDir();
+
+  if (dir && !currentPath.split(delimiter).includes(dir)) {
+    return `${dir}${delimiter}${currentPath}`;
+  }
+
+  return currentPath;
+}
+
+/**
+ * Reset cached resolution (for testing).
+ */
+export function resetOpenCodeCache(): void {
+  _openCodeDir = null;
+}

src/web/public/app.js

@@ -5239,8 +5239,6 @@ class CodemanApp {
     this._localEchoOverlay?.rerender();
     // Clear pending hooks
     this.pendingHooks.clear();
-    // Clear parent name cache (prevents stale session name entries accumulating)
-    if (this._parentNameCache) this._parentNameCache.clear();
     // Clear subagent activity/results maps (prevents leaks if data.subagents is missing)
     this.subagentActivity.clear();
     this.subagentToolResults.clear();
@@ -6391,7 +6389,7 @@ class CodemanApp {
         const displayName = c.name.length > maxNameLength
           ? c.name.substring(0, maxNameLength) + '…'
           : c.name;
-        options += `<option value="${this.escapeHtml(c.name)}">${this.escapeHtml(displayName)}</option>`;
+        options += `<option value="${c.name}">${displayName}</option>`;
       });
 
       // Add testcase option if it doesn't exist (will be created on first run)
@@ -8948,16 +8946,17 @@ class CodemanApp {
     const isActive = btn.classList.contains('active');
     btn.disabled = true;
     try {
+      const res = await fetch('/api/settings');
+      const current = res.ok ? await res.json() : {};
       const newEnabled = !isActive;
+      current.tunnelEnabled = newEnabled;
       await fetch('/api/settings', {
         method: 'PUT',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ tunnelEnabled: newEnabled }),
+        body: JSON.stringify(current),
       });
       if (newEnabled) {
         this._showTunnelConnecting();
-        // Poll tunnel status as fallback in case SSE event is missed
-        this._pollTunnelStatus();
       } else {
         this._dismissTunnelConnecting();
         this.showToast('Tunnel stopped', 'info');
@@ -9002,8 +9001,6 @@ class CodemanApp {
   }
 
   _dismissTunnelConnecting() {
-    clearTimeout(this._tunnelPollTimer);
-    this._tunnelPollTimer = null;
     const toast = document.getElementById('tunnelConnectingToast');
     if (toast) {
       toast.classList.remove('show');
@@ -9013,32 +9010,6 @@ class CodemanApp {
     if (btn) btn.classList.remove('connecting');
   }
 
-  _pollTunnelStatus(attempt = 0) {
-    if (attempt > 15) return; // give up after ~30s
-    this._tunnelPollTimer = setTimeout(async () => {
-      try {
-        const res = await fetch('/api/tunnel/status');
-        const status = await res.json();
-        if (status.running && status.url) {
-          // Tunnel is up — update UI
-          this._dismissTunnelConnecting();
-          this._updateTunnelUrlDisplay(status.url);
-          const welcomeVisible = document.getElementById('welcomeOverlay')?.classList.contains('visible');
-          if (welcomeVisible) {
-            this._updateWelcomeTunnelBtn(true, status.url, true);
-            this.showToast('Tunnel active', 'success');
-          } else {
-            this._updateWelcomeTunnelBtn(true, status.url);
-            this.showToast(`Tunnel active: ${status.url}`, 'success');
-            this.showTunnelQR();
-          }
-          return;
-        }
-      } catch { /* ignore */ }
-      this._pollTunnelStatus(attempt + 1);
-    }, 2000);
-  }
-
   _updateWelcomeTunnelBtn(active, url, firstAppear = false) {
     const btn = document.getElementById('welcomeTunnelBtn');
     if (btn) {
@@ -12011,6 +11982,8 @@ class CodemanApp {
     const svg = document.getElementById('connectionLines');
     if (!svg) return;
 
+    svg.innerHTML = '';
+
     // Check if Ralph wizard modal is open
     const wizardModal = document.getElementById('ralphWizardModal');
     const wizardOpen = wizardModal?.classList.contains('active');
@@ -12030,51 +12003,8 @@ class CodemanApp {
       .filter(([, data]) => data.element)
       .map(([id, data]) => ({ id, ...data }));
 
-    // === PHASE 1: Batch all layout reads (getBoundingClientRect) ===
-    // Reading layout properties forces the browser to calculate layout.
-    // By batching all reads before any writes, we avoid repeated forced reflows.
-    const rects = new Map();
-
-    // Read all subagent window rects
     for (const { agentId, win } of visibleSubagentWindows) {
-      rects.set('sub:' + agentId, win.getBoundingClientRect());
-    }
-
-    // Read all plan subagent rects
-    for (const planAgent of planSubagentArray) {
-      rects.set('plan:' + planAgent.id, planAgent.element.getBoundingClientRect());
-    }
-
-    // Read wizard rect (if open)
-    let wizardRect = null;
-    if (wizardOpen && wizardContent) {
-      wizardRect = wizardContent.getBoundingClientRect();
-    }
-
-    // Read tab rects for normal mode (only tabs that are actually needed)
-    if (!wizardOpen) {
-      for (const { agentId } of visibleSubagentWindows) {
-        const parentSessionId = this.subagentParentMap.get(agentId);
-        if (!parentSessionId || rects.has('tab:' + parentSessionId)) continue;
-        const tab = document.querySelector(`.session-tab[data-id="${parentSessionId}"]`);
-        if (tab) rects.set('tab:' + parentSessionId, tab.getBoundingClientRect());
-      }
-    }
-
-    // Read plan window rects for wizard-to-plan lines
-    if (wizardOpen && wizardContent && this.planSubagents.size > 0 && !this.planAgentsMinimized) {
-      for (const [agentId, windowData] of this.planSubagents) {
-        if (!windowData.element) continue;
-        const key = 'planwin:' + agentId;
-        if (!rects.has(key)) rects.set(key, windowData.element.getBoundingClientRect());
-      }
-    }
-
-    // === PHASE 2: DOM writes using cached rects (no more layout reads) ===
-    svg.innerHTML = '';
-
-    for (const { agentId } of visibleSubagentWindows) {
-      const winRect = rects.get('sub:' + agentId);
+      const winRect = win.getBoundingClientRect();
 
       // If wizard is open with plan subagents, connect regular subagents to plan subagent windows
       if (wizardOpen && wizardContent && planSubagentArray.length > 0) {
@@ -12083,7 +12013,7 @@ class CodemanApp {
         let nearestDistance = Infinity;
 
         for (const planAgent of planSubagentArray) {
-          const planRect = rects.get('plan:' + planAgent.id);
+          const planRect = planAgent.element.getBoundingClientRect();
           const planCenterX = planRect.left + planRect.width / 2;
           const planCenterY = planRect.top + planRect.height / 2;
           const winCenterX = winRect.left + winRect.width / 2;
@@ -12097,7 +12027,7 @@ class CodemanApp {
         }
 
         if (nearestPlanAgent) {
-          const planRect = rects.get('plan:' + nearestPlanAgent.id);
+          const planRect = nearestPlanAgent.element.getBoundingClientRect();
 
           // Draw line from plan subagent window to regular subagent window
           let x1, y1, x2, y2;
@@ -12128,6 +12058,8 @@ class CodemanApp {
         }
       } else if (wizardOpen && wizardContent) {
         // Wizard open but no plan subagents - connect directly to wizard
+        const wizardRect = wizardContent.getBoundingClientRect();
+
         const winCenterX = winRect.left + winRect.width / 2;
         const wizardCenterX = wizardRect.left + wizardRect.width / 2;
 
@@ -12163,12 +12095,15 @@ class CodemanApp {
           continue;
         }
 
-        const tabRect = rects.get('tab:' + parentSessionId);
-        if (!tabRect) {
+        // Find the TAB element by its data-id
+        const tab = document.querySelector(`.session-tab[data-id="${parentSessionId}"]`);
+        if (!tab) {
           // Tab not in DOM (might be scrolled out or session closed)
           continue;
         }
 
+        const tabRect = tab.getBoundingClientRect();
+
         // Draw curved line from TAB bottom-center to window top-center
         const x1 = tabRect.left + tabRect.width / 2;
         const y1 = tabRect.bottom;
@@ -12191,9 +12126,13 @@ class CodemanApp {
     // Draw lines from wizard to plan subagent windows (Opus agents during plan generation)
     // Skip if agents are minimized to tab
     if (wizardOpen && wizardContent && this.planSubagents.size > 0 && !this.planAgentsMinimized) {
-      for (const [agentId] of this.planSubagents) {
-        const winRect = rects.get('planwin:' + agentId);
-        if (!winRect) continue;
+      const wizardRect = wizardContent.getBoundingClientRect();
+
+      for (const [agentId, windowData] of this.planSubagents) {
+        const win = windowData.element;
+        if (!win) continue;
+
+        const winRect = win.getBoundingClientRect();
 
         // Determine which side of wizard the window is on
         const winCenterX = winRect.left + winRect.width / 2;

src/web/server.ts

@@ -16,17 +16,7 @@ import fastifyCookie from '@fastify/cookie';
 import fastifyStatic from '@fastify/static';
 import { join, dirname, resolve, relative, isAbsolute } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import {
-  existsSync,
-  statSync,
-  mkdirSync,
-  writeFileSync,
-  readdirSync,
-  readFileSync,
-  rmSync,
-  chmodSync,
-  realpathSync,
-} from 'node:fs';
+import { existsSync, statSync, mkdirSync, writeFileSync, readdirSync, readFileSync, rmSync, chmodSync } from 'node:fs';
 import fs from 'node:fs/promises';
 import { execSync } from 'node:child_process';
 import { randomBytes, timingSafeEqual } from 'node:crypto';
@@ -995,10 +985,10 @@ export class WebServer extends EventEmitter {
           },
         },
         watchers: {
-          fileDebouncers: subagentStats.fileDebouncerCount,
+          fileWatchers: subagentStats.fileWatcherCount,
           dirWatchers: subagentStats.dirWatcherCount,
           transcriptWatchers: this.transcriptWatchers.size,
-          total: subagentStats.fileDebouncerCount + subagentStats.dirWatcherCount + this.transcriptWatchers.size,
+          total: subagentStats.fileWatcherCount + subagentStats.dirWatcherCount + this.transcriptWatchers.size,
         },
         timers: {
           respawnTimers: this.respawnTimers.size,
@@ -1401,21 +1391,15 @@ export class WebServer extends EventEmitter {
         return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Missing path parameter');
       }
 
-      // Validate path is within working directory (security: resolve symlinks to prevent traversal)
+      // Validate path is within working directory (security: proper path traversal check)
       const fullPath = resolve(session.workingDir, filePath);
-      let resolvedPath: string;
-      try {
-        resolvedPath = realpathSync(fullPath);
-      } catch {
-        return createErrorResponse(ApiErrorCode.NOT_FOUND, 'File not found');
-      }
-      const relativePath = relative(session.workingDir, resolvedPath);
+      const relativePath = relative(session.workingDir, fullPath);
       if (relativePath.startsWith('..') || isAbsolute(relativePath)) {
         return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Path must be within working directory');
       }
 
       try {
-        const stat = await fs.stat(resolvedPath);
+        const stat = await fs.stat(fullPath);
 
         // Check if it's a binary/media file
         const ext = filePath.split('.').pop()?.toLowerCase() || '';
@@ -1476,7 +1460,7 @@ export class WebServer extends EventEmitter {
         // Read text file with line limit (bounded to prevent DoS)
         const MAX_LINES_LIMIT = 10000;
         const maxLines = Math.min(parseInt(lines || '500', 10) || 500, MAX_LINES_LIMIT);
-        const content = await fs.readFile(resolvedPath, 'utf-8');
+        const content = await fs.readFile(fullPath, 'utf-8');
         const allLines = content.split('\n');
         const truncatedContent = allLines.length > maxLines;
         const displayContent = truncatedContent ? allLines.slice(0, maxLines).join('\n') : content;
@@ -1513,16 +1497,9 @@ export class WebServer extends EventEmitter {
         return;
       }
 
-      // Validate path is within working directory (security: resolve symlinks to prevent traversal)
+      // Validate path is within working directory (security: proper path traversal check)
       const fullPath = resolve(session.workingDir, filePath);
-      let resolvedPath: string;
-      try {
-        resolvedPath = realpathSync(fullPath);
-      } catch {
-        reply.code(404).send(createErrorResponse(ApiErrorCode.NOT_FOUND, 'File not found'));
-        return;
-      }
-      const relativePath = relative(session.workingDir, resolvedPath);
+      const relativePath = relative(session.workingDir, fullPath);
       if (relativePath.startsWith('..') || isAbsolute(relativePath)) {
         reply.code(400).send(createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Path must be within working directory'));
         return;
@@ -1531,7 +1508,7 @@ export class WebServer extends EventEmitter {
       try {
         // Validate file size before reading (DoS protection - prevent memory exhaustion)
         const MAX_RAW_FILE_SIZE = 50 * 1024 * 1024; // 50MB for raw files
-        const stat = await fs.stat(resolvedPath);
+        const stat = await fs.stat(fullPath);
         if (stat.size > MAX_RAW_FILE_SIZE) {
           reply
             .code(400)
@@ -1564,7 +1541,7 @@ export class WebServer extends EventEmitter {
           json: 'application/json',
         };
 
-        const content = await fs.readFile(resolvedPath);
+        const content = await fs.readFile(fullPath);
         reply.header('Content-Type', mimeTypes[ext] || 'application/octet-stream');
         reply.send(content);
       } catch (err) {
@@ -4056,10 +4033,6 @@ NOW: Generate the implementation plan for the task above. Think step by step.`;
           if (tunnelEnabled && !this.tunnelManager.isRunning()) {
             this.tunnelManager.start(this.port, this.https);
             console.log('Tunnel started via settings change');
-          } else if (tunnelEnabled && this.tunnelManager.isRunning() && this.tunnelManager.getUrl()) {
-            // Tunnel already running — re-emit so the client gets the URL
-            this.broadcast('tunnel:started', { url: this.tunnelManager.getUrl() });
-            console.log('Tunnel already running, re-broadcast URL to client');
           } else if (!tunnelEnabled && this.tunnelManager.isRunning()) {
             this.tunnelManager.stop();
             console.log('Tunnel stopped via settings change');
@@ -4844,13 +4817,6 @@ NOW: Generate the implementation plan for the task above. Think step by step.`;
       this.runSummaryTrackers.delete(sessionId);
     }
 
-    // Clear pending persist-debounce timer (prevents stale closure holding session ref)
-    const pendingPersist = this.persistDebounceTimers.get(sessionId);
-    if (pendingPersist) {
-      clearTimeout(pendingPersist);
-      this.persistDebounceTimers.delete(sessionId);
-    }
-
     // Clear batches, per-session timers, and pending state updates
     this.terminalBatches.delete(sessionId);
     this.terminalBatchSizes.delete(sessionId);
@@ -5050,79 +5016,6 @@ NOW: Generate the implementation plan for the task above. Think step by step.`;
         } catch (err) {
           console.error(`[Server] Error cleaning up respawn controller for ${session.id}:`, err);
         }
-
-        // Clean up per-session resources that are stale after PTY exit.
-        // These are only cleaned by cleanupSession() on explicit delete,
-        // so without this they leak when a session exits without deletion.
-        try {
-          // Transcript watcher is tied to the specific PTY run
-          this.stopTranscriptWatcher(session.id);
-
-          // Finalize run summary tracker
-          const summaryTracker = this.runSummaryTrackers.get(session.id);
-          if (summaryTracker) {
-            summaryTracker.recordSessionStopped();
-            summaryTracker.stop();
-            this.runSummaryTrackers.delete(session.id);
-          }
-
-          // Flush/clear terminal batching state (no more output coming)
-          this.terminalBatches.delete(session.id);
-          this.terminalBatchSizes.delete(session.id);
-          const batchTimer = this.terminalBatchTimers.get(session.id);
-          if (batchTimer) {
-            clearTimeout(batchTimer);
-            this.terminalBatchTimers.delete(session.id);
-          }
-          this.taskUpdateBatches.delete(session.id);
-          this.stateUpdatePending.delete(session.id);
-          this.lastTerminalEventTime.delete(session.id);
-
-          // Clear pending persist-debounce timer
-          const pendingPersist = this.persistDebounceTimers.get(session.id);
-          if (pendingPersist) {
-            clearTimeout(pendingPersist);
-            this.persistDebounceTimers.delete(session.id);
-          }
-
-          // Close any active file streams
-          fileStreamManager.closeSessionStreams(session.id);
-
-          // Remove stored listener refs to break closure references (prevents memory leak).
-          // Without this, the closures capture the Session object (including up to 2MB terminal buffer)
-          // and keep it alive even after the PTY exits.
-          const listenerRefs = this.sessionListenerRefs.get(session.id);
-          if (listenerRefs) {
-            session.off('terminal', listenerRefs.terminal);
-            session.off('clearTerminal', listenerRefs.clearTerminal);
-            session.off('needsRefresh', listenerRefs.needsRefresh);
-            session.off('message', listenerRefs.message);
-            session.off('error', listenerRefs.error);
-            session.off('completion', listenerRefs.completion);
-            session.off('exit', listenerRefs.exit);
-            session.off('working', listenerRefs.working);
-            session.off('idle', listenerRefs.idle);
-            session.off('taskCreated', listenerRefs.taskCreated);
-            session.off('taskUpdated', listenerRefs.taskUpdated);
-            session.off('taskCompleted', listenerRefs.taskCompleted);
-            session.off('taskFailed', listenerRefs.taskFailed);
-            session.off('autoClear', listenerRefs.autoClear);
-            session.off('autoCompact', listenerRefs.autoCompact);
-            session.off('cliInfoUpdated', listenerRefs.cliInfoUpdated);
-            session.off('ralphLoopUpdate', listenerRefs.ralphLoopUpdate);
-            session.off('ralphTodoUpdate', listenerRefs.ralphTodoUpdate);
-            session.off('ralphCompletionDetected', listenerRefs.ralphCompletionDetected);
-            session.off('ralphStatusBlockDetected', listenerRefs.ralphStatusBlockDetected);
-            session.off('ralphCircuitBreakerUpdate', listenerRefs.ralphCircuitBreakerUpdate);
-            session.off('ralphExitGateMet', listenerRefs.ralphExitGateMet);
-            session.off('bashToolStart', listenerRefs.bashToolStart);
-            session.off('bashToolEnd', listenerRefs.bashToolEnd);
-            session.off('bashToolsUpdate', listenerRefs.bashToolsUpdate);
-            this.sessionListenerRefs.delete(session.id);
-          }
-        } catch (err) {
-          console.error(`[Server] Error cleaning up session resources on exit for ${session.id}:`, err);
-        }
       },
 
       working: () => {
@@ -5878,17 +5771,15 @@ NOW: Generate the implementation plan for the task above. Think step by step.`;
   }
 
   private broadcast(event: string, data: unknown): void {
-    // Invalidate caches only on structurally significant events — ones that
-    // change session list content (creation, deletion, or full state refresh).
-    // High-frequency non-structural events (working/idle transitions, completion,
-    // error, respawn state changes) are NOT worth invalidating for because:
-    //   1. The debounced session:updated follows within 500ms with the new state
-    //   2. These caches serve /api/sessions and SSE init — neither is polled rapidly
-    //   3. Invalidating on every working/idle transition makes the 1s TTL useless
+    // Invalidate caches on state-changing broadcasts, but NOT on high-frequency
+    // streaming events that don't change session metadata (terminal data,
+    // detection updates). These fire every 16ms-2s and would make the 1s TTL
+    // caches permanently empty — defeating their purpose.
     if (
-      event === 'session:created' ||
-      event === 'session:deleted' ||
-      event === 'session:updated'
+      (event.startsWith('session:') || event.startsWith('respawn:')) &&
+      event !== 'session:terminal' &&
+      event !== 'session:needsRefresh' &&
+      event !== 'respawn:detectionUpdate'
     ) {
       this.cachedLightState = null;
       this.cachedSessionsList = null;
@@ -6263,19 +6154,10 @@ NOW: Generate the implementation plan for the task above. Think step by step.`;
       console.log('Image watcher disabled by user settings');
     }
 
-    // Tunnel only starts when user clicks the toggle in the UI — never on boot.
-    // Reset persisted tunnelEnabled so the UI toggle reflects actual state.
+    // Start Cloudflare tunnel if enabled in settings
     if (await this.isTunnelEnabled()) {
-      const settingsPath = join(homedir(), '.codeman', 'settings.json');
-      try {
-        const content = await fs.readFile(settingsPath, 'utf-8');
-        const settings = JSON.parse(content);
-        settings.tunnelEnabled = false;
-        await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2));
-      } catch {
-        /* ignore */
-      }
-      console.log('Cloudflare tunnel setting reset (tunnel only starts on explicit UI toggle)');
+      this.tunnelManager.start(this.port, this.https);
+      console.log('Cloudflare tunnel starting on boot (enabled in settings)');
     }
 
     // Start team watcher for agent team awareness (always on — lightweight polling)
@@ -6701,9 +6583,6 @@ NOW: Generate the implementation plan for the task above. Think step by step.`;
     }
 
     // Clear remaining Maps that accumulate session references
-    for (const { timer } of this.respawnTimers.values()) {
-      clearTimeout(timer);
-    }
     this.respawnTimers.clear();
     this.runSummaryTrackers.clear();
     this.transcriptWatchers.clear();

test/hooks-config.test.ts

@@ -667,8 +667,8 @@ describe('Hook Config Generation - Extended', () => {
 
     for (const hook of notifHooks) {
       const cmd = hook.hooks[0].command;
-      // The printf format string contains the event name baked in
-      expect(cmd).toContain(`"event":"${hook.matcher}"`);
+      // The command contains escaped quotes for the JSON payload: \"event\":\"idle_prompt\"
+      expect(cmd).toContain(`\\"event\\":\\"${hook.matcher}\\"`);
     }
   });
 
@@ -684,9 +684,8 @@ describe('Hook Config Generation - Extended', () => {
     const notifHooks = config.hooks.Notification as Array<{ hooks: Array<{ command: string }> }>;
     const cmd = notifHooks[0].hooks[0].command;
     expect(cmd).toContain('HOOK_DATA=$(cat');
-    // Data is piped to curl via stdin (--data @-) to prevent shell injection
-    expect(cmd).toContain('$HOOK_DATA');
-    expect(cmd).toContain('--data @-');
+    // The data field in the JSON uses escaped quotes: \"data\":$HOOK_DATA
+    expect(cmd).toContain('\\"data\\":$HOOK_DATA');
   });
 
   it('should have consistent structure across all notification hooks', () => {
@@ -702,18 +701,6 @@ describe('Hook Config Generation - Extended', () => {
     }
   });
 
-  it('should pipe data to curl via stdin to prevent shell injection', () => {
-    const config = generateHooksConfig();
-    const notifHooks = config.hooks.Notification as Array<{ hooks: Array<{ command: string }> }>;
-    const cmd = notifHooks[0].hooks[0].command;
-    // HOOK_DATA must NOT be embedded unquoted in a -d "..." argument (shell injection vector)
-    expect(cmd).not.toMatch(/-d\s+"[^"]*\$HOOK_DATA/);
-    // Instead, data should be piped to curl via stdin
-    expect(cmd).toContain('printf');
-    expect(cmd).toContain('| curl');
-    expect(cmd).toContain('--data @-');
-  });
-
   it('should have stop hook without matcher (catches all)', () => {
     const config = generateHooksConfig();
     const stopHooks = config.hooks.Stop as Array<{ matcher?: string; hooks: Array<{ command: string }> }>;

test/state-store.test.ts

@@ -6,7 +6,7 @@
  */
 
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import { existsSync, unlinkSync, mkdirSync, rmSync, readFileSync } from 'node:fs';
+import { existsSync, unlinkSync, mkdirSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 
@@ -360,7 +360,7 @@ describe('StateStore', () => {
       const store = new StateStore(testFilePath);
 
       store.addToGlobalStats(1000, 500, 0.05);
-      store.addToGlobalStats(2000, 1000, 0.1);
+      store.addToGlobalStats(2000, 1000, 0.10);
 
       const stats = store.getGlobalStats();
       expect(stats.totalInputTokens).toBe(3000);
@@ -388,20 +388,20 @@ describe('StateStore', () => {
       // Simulate active sessions
       const activeSessions = {
         'session-1': { inputTokens: 1000, outputTokens: 500, totalCost: 0.05 },
-        'session-2': { inputTokens: 2000, outputTokens: 1000, totalCost: 0.1 },
+        'session-2': { inputTokens: 2000, outputTokens: 1000, totalCost: 0.10 },
       };
 
       const aggregate = store.getAggregateStats(activeSessions);
 
       expect(aggregate.totalInputTokens).toBe(8000); // 5000 + 1000 + 2000
       expect(aggregate.totalOutputTokens).toBe(4000); // 2500 + 500 + 1000
-      expect(aggregate.totalCost).toBeCloseTo(0.4, 10); // 0.25 + 0.05 + 0.10
+      expect(aggregate.totalCost).toBeCloseTo(0.40, 10); // 0.25 + 0.05 + 0.10
       expect(aggregate.activeSessionsCount).toBe(2);
     });
 
     it('should persist global stats across instances', () => {
       const store1 = new StateStore(testFilePath);
-      store1.addToGlobalStats(10000, 5000, 0.5);
+      store1.addToGlobalStats(10000, 5000, 0.50);
       store1.incrementSessionsCreated();
       store1.flushAll();
 
@@ -410,105 +410,10 @@ describe('StateStore', () => {
 
       expect(stats.totalInputTokens).toBe(10000);
       expect(stats.totalOutputTokens).toBe(5000);
-      expect(stats.totalCost).toBe(0.5);
+      expect(stats.totalCost).toBe(0.50);
       expect(stats.totalSessionsCreated).toBe(1);
     });
   });
-
-  describe('assembleStateJson', () => {
-    it('should produce output identical to JSON.stringify(state)', () => {
-      const store = new StateStore(testFilePath);
-
-      // Add sessions, tasks, config changes
-      store.setSession('s1', createMockSessionState('s1'));
-      store.setSession('s2', createMockSessionState('s2'));
-      store.setTask('t1', createMockTaskState('t1'));
-      store.setConfig({ maxConcurrentSessions: 5 });
-      store.addToGlobalStats(1000, 500, 0.05);
-
-      // Force a save so assembleStateJson is called
-      store.saveNow();
-
-      // Read persisted file and compare with full JSON.stringify
-      const persisted = JSON.parse(readFileSync(testFilePath, 'utf-8'));
-      const fullStringify = JSON.parse(JSON.stringify(store.getState()));
-
-      expect(persisted).toEqual(fullStringify);
-    });
-
-    it('should correctly persist all sessions after partial update', () => {
-      const store = new StateStore(testFilePath);
-
-      // Create 10 sessions
-      for (let i = 0; i < 10; i++) {
-        store.setSession(`s${i}`, createMockSessionState(`s${i}`));
-      }
-      store.saveNow();
-
-      // Modify only 1 session
-      const updated = createMockSessionState('s3');
-      updated.status = 'idle';
-      updated.pid = 99999;
-      store.setSession('s3', updated);
-      store.saveNow();
-
-      // Read from disk and verify all 10 sessions are present and correct
-      const persisted = JSON.parse(readFileSync(testFilePath, 'utf-8'));
-      expect(Object.keys(persisted.sessions)).toHaveLength(10);
-
-      // The updated session should have the new values
-      expect(persisted.sessions['s3'].status).toBe('idle');
-      expect(persisted.sessions['s3'].pid).toBe(99999);
-
-      // Other sessions should be unchanged
-      for (let i = 0; i < 10; i++) {
-        if (i === 3) continue;
-        expect(persisted.sessions[`s${i}`].id).toBe(`s${i}`);
-        expect(persisted.sessions[`s${i}`].status).toBe('running');
-      }
-    });
-
-    it('should handle session removal and prune cache correctly', () => {
-      const store = new StateStore(testFilePath);
-
-      store.setSession('s1', createMockSessionState('s1'));
-      store.setSession('s2', createMockSessionState('s2'));
-      store.setSession('s3', createMockSessionState('s3'));
-      store.saveNow();
-
-      // Remove s2
-      store.removeSession('s2');
-      store.saveNow();
-
-      const persisted = JSON.parse(readFileSync(testFilePath, 'utf-8'));
-      expect(Object.keys(persisted.sessions)).toHaveLength(2);
-      expect(persisted.sessions['s1']).toBeDefined();
-      expect(persisted.sessions['s2']).toBeUndefined();
-      expect(persisted.sessions['s3']).toBeDefined();
-
-      // Verify round-trip: state in memory matches what's on disk
-      const fullStringify = JSON.parse(JSON.stringify(store.getState()));
-      expect(persisted).toEqual(fullStringify);
-    });
-
-    it('should persist the last value after rapid updates to the same session', () => {
-      const store = new StateStore(testFilePath);
-
-      // Rapidly update the same session 100 times
-      for (let i = 0; i < 100; i++) {
-        const session = createMockSessionState('rapid');
-        session.pid = i;
-        store.setSession('rapid', session);
-      }
-
-      // Only one save at the end
-      store.saveNow();
-
-      const persisted = JSON.parse(readFileSync(testFilePath, 'utf-8'));
-      expect(persisted.sessions['rapid']).toBeDefined();
-      expect(persisted.sessions['rapid'].pid).toBe(99); // Last value wins
-    });
-  });
 });
 
 // Helper functions to create mock state objects

test/subagent-watcher.test.ts

@@ -1236,24 +1236,7 @@ describe('SubagentWatcher', () => {
 
       const mockRl = new EventEmitter();
       mockCreateInterface.mockReturnValue(mockRl);
-
-      // createReadStream now used for parent transcript reading (stream tail)
-      // Return a stream-like EventEmitter that emits the transcript content
-      mockCreateReadStream.mockImplementation((filepath: string) => {
-        const stream = new EventEmitter() as EventEmitter & { destroy: () => void };
-        stream.destroy = vi.fn();
-        if (typeof filepath === 'string' && filepath.includes('session1.jsonl')) {
-          // Emit parent transcript content on next tick
-          process.nextTick(() => {
-            stream.emit('data', parentTranscript + '\n');
-            stream.emit('end');
-          });
-        } else {
-          // For agent files, emit end immediately (empty content)
-          process.nextTick(() => stream.emit('end'));
-        }
-        return stream;
-      });
+      mockCreateReadStream.mockReturnValue({});
 
       mockExistsSync.mockReturnValue(true);
       mockReaddirSync.mockImplementation((path: string) => {
@@ -1268,6 +1251,14 @@ describe('SubagentWatcher', () => {
         mtime: new Date(),
         size: 100,
       });
+      // Return parent transcript when reading the session transcript
+      // Return empty for subagent file (will fall back, but we want to test parent extraction)
+      mockReadFileSync.mockImplementation((filepath: string) => {
+        if (filepath.includes('session1.jsonl')) {
+          return parentTranscript;
+        }
+        return ''; // Empty subagent file
+      });
 
       const discoveredHandler = vi.fn();
       watcher.on('subagent:discovered', discoveredHandler);
@@ -1518,11 +1509,14 @@ describe('SubagentWatcher', () => {
   });
 
   describe('File Watcher Management', () => {
-    it('should close directory watchers on stop', async () => {
+    it('should close file watchers on stop', async () => {
+      const mockFileWatcher = { close: vi.fn(), on: vi.fn(), off: vi.fn() };
       const mockDirWatcher = { close: vi.fn(), on: vi.fn(), off: vi.fn() };
 
-      // Only directory watchers are created (no per-file watchers)
-      mockWatch.mockReturnValue(mockDirWatcher);
+      mockWatch.mockImplementation((path: string) => {
+        if (path.endsWith('.jsonl')) return mockFileWatcher;
+        return mockDirWatcher;
+      });
 
       const mockRl = new EventEmitter();
       mockCreateInterface.mockReturnValue(mockRl);
@@ -1551,8 +1545,8 @@ describe('SubagentWatcher', () => {
 
       watcher.stop();
 
-      // Directory watchers should be closed (per-file watchers no longer exist)
-      expect(mockDirWatcher.close).toHaveBeenCalled();
+      // Watchers should be closed
+      expect(mockFileWatcher.close).toHaveBeenCalled();
     });
 
     it('should clear idle timers on stop', async () => {