Content
;
+};
+```
+ Content
;
+};
+```
+ {item}
;
+})}
+```
+
+
+ ...
+
+```
+
+
+ - Inside a `<Sequence>`, `useCurrentFrame()` resets to 0 at the Sequence's `from` frame.
+ - To limit duration without wrapping in Sequence, pass `durationInFrames` as a prop
+ and use `Math.min(frame, durationInFrames - 1)` as your animation input.
+ - To trim the start of a clip (skip first N frames), set `from={-N}`.
+ - Avoid deeply nested Sequences unless necessary — they reset the frame counter
+ at each level, which can be confusing.
+
+
+
+
+
+ Defining Compositions
+
+```tsx
+// src/Root.tsx — always the entry point
+import { Composition } from 'remotion';
+import { MyVideo } from './MyVideo';
+
+export const RemotionRoot: React.FC = () => {
+ return (
+ <>
+
+ - Every video must be registered in a `<Composition>`.
+ - `id` must be unique across the project and match what you pass to the CLI.
+ - For dynamic duration (e.g., based on audio length), use `calculateMetadata`.
+ - Stills: use `<Still>` instead of `<Composition>` — no `durationInFrames` needed.
+ - Folders: wrap compositions in `<Folder>` for Studio organization — no functional effect.
+
+
+
+
+
+ Dynamic Composition Duration and Props
+
+```tsx
+import { Composition } from 'remotion';
+import { getAudioDurationInSeconds } from '@remotion/media-utils';
+
+const calculateMetadata = async ({ props }) => {
+ const audioDuration = await getAudioDurationInSeconds(
+ staticFile(props.audioFile)
+ );
+ return {
+ durationInFrames: Math.ceil(audioDuration * props.fps),
+ props, // pass through unchanged
+ };
+};
+
+
+ - Use `calculateMetadata` when duration depends on external data (audio length,
+ number of slides, API response, etc.).
+ - Can also override `width`, `height`, `fps` dynamically.
+ - The function is async — you can fetch data, read files, etc.
+ - Keep it pure and fast — it's called every time the composition is rendered.
+
+
+
+
+
+ Interpolation Curves and Easing
+
+```tsx
+import { interpolate, Easing } from 'remotion';
+
+// Common easing patterns
+const easeOut = interpolate(frame, [0, 30], [0, 1], {
+ extrapolateRight: 'clamp',
+ easing: Easing.out(Easing.cubic),
+});
+const easeIn = interpolate(frame, [0, 30], [0, 1], {
+ extrapolateRight: 'clamp',
+ easing: Easing.in(Easing.cubic),
+});
+const easeInOut = interpolate(frame, [0, 30], [0, 1], {
+ extrapolateRight: 'clamp',
+ easing: Easing.inOut(Easing.sin),
+});
+const bounce = interpolate(frame, [0, 30], [0, 1], {
+ extrapolateRight: 'clamp',
+ easing: Easing.bounce,
+});
+const elastic = interpolate(frame, [0, 30], [0, 1], {
+ extrapolateRight: 'clamp',
+ easing: Easing.elastic(1),
+});
+
+// Bezier (CSS cubic-bezier equivalent)
+const bezier = interpolate(frame, [0, 30], [0, 1], {
+ extrapolateRight: 'clamp',
+ easing: Easing.bezier(0.25, 0.1, 0.25, 1),
+});
+```
+
+
+ - `Easing` is from the `remotion` package — same API as React Native's Animated.
+ - For spring physics, use `spring()` instead of eased `interpolate()`.
+ - Spring config guide:
+ - `{ damping: 200 }` → overdamped, snappy, no bounce
+ - `{ damping: 100 }` → slight overshoot
+ - `{ mass: 0.5, stiffness: 200, damping: 15 }` → bouncy
+ - Do not mix `spring()` and `interpolate()` for the same value — pick one.
+
+
+
+
+
+ Scene Transitions
+
+```tsx
+import { TransitionSeries, linearTiming, springTiming } from '@remotion/transitions';
+import { slide } from '@remotion/transitions/slide';
+import { fade } from '@remotion/transitions/fade';
+import { wipe } from '@remotion/transitions/wipe';
+import { flip } from '@remotion/transitions/flip';
+import { clockWipe } from '@remotion/transitions/clock-wipe';
+
+// CRITICAL: Total duration = sum of scenes MINUS sum of transition durations
+// Example: 60 + 60 - 15 = 105 frames total
+const timing = linearTiming({ durationInFrames: 15 });
+
+
+
+
+
+
+
+```
+
+```tsx
+// Calculate total duration correctly
+const scene1 = 60, scene2 = 60, transitionDuration = 15;
+const total = scene1 + scene2 - transitionDuration; // 105
+
+// Spring timing — organic feel
+
+ - Install: `npx remotion add @remotion/transitions`
+ - Slide directions: `'from-left' | 'from-right' | 'from-top' | 'from-bottom'`
+ - Transitions overlap adjacent scenes — always subtract transition duration from total.
+ - Use `timing.getDurationInFrames({ fps })` to compute duration programmatically.
+
+
+
+
+
+ Importing Assets (images, video, audio, fonts)
+
+```tsx
+import { staticFile, Img, Video, Audio } from 'remotion';
+
+// Always use staticFile() for assets in /public
+})
+
+
+
+// Dynamic paths
+})
+
+// Remote URLs work too
+
+```
+
+
+ - NEVER use `<img>`, `<video>`, `<audio>` — use Remotion's versions.
+ - All static assets go in `/public`. Access via `staticFile('filename.ext')`.
+ - `<Img>` blocks rendering until the image loads — prevents blank frames.
+ - `<Video>` blocks rendering until video metadata loads.
+ - For animated GIFs, use `<Gif>` from `@remotion/gif` — NOT `<Img>`.
+
+
+
+
+
+ Audio — importing, trimming, volume, speed, pitch
+
+```tsx
+import { Audio, staticFile } from 'remotion';
+import { linearTiming } from '@remotion/transitions';
+
+// Basic audio
+
+
+// Trim: start at 5s, play 10s worth
+
+
+// Volume fade-out over last 30 frames
+
+
+
+
+ Audio Visualization — spectrum bars, waveforms, bass-reactive
+
+```tsx
+import { useAudioData, visualizeAudio } from '@remotion/media-utils';
+import { Audio, staticFile, useCurrentFrame, useVideoConfig } from 'remotion';
+
+export const AudioBars: React.FC = () => {
+ const frame = useCurrentFrame();
+ const { fps, width, height } = useVideoConfig();
+ const audioData = useAudioData(staticFile('music.mp3'));
+
+ if (!audioData) return null;
+
+ const frequencyData = visualizeAudio({
+ fps,
+ frame,
+ audioData,
+ numberOfSamples: 64, // number of bars
+ smoothing: true,
+ });
+
+ return (
+
+ - Install: `npm install @remotion/media-utils`
+ - `useAudioData()` returns null on first render — always guard with `if (!audioData) return null`.
+ - `visualizeAudio()` returns normalized values 0–1.
+ - `smoothing: true` reduces jitter between frames.
+ - Bass is at low indices (0-5), treble at high indices (50-63) for 64 samples.
+
+
+
+
+
+ Fonts — Google Fonts and local fonts
+
+```tsx
+// Google Fonts — use @remotion/google-fonts
+import { loadFont } from '@remotion/google-fonts/Roboto';
+
+const { fontFamily } = loadFont();
+// use fontFamily in style={{ fontFamily }}
+
+// Alternative: manual font loading with delayRender
+import { delayRender, continueRender } from 'remotion';
+
+const handle = delayRender('Loading font');
+const font = new FontFace('MyFont', 'url(/public/MyFont.woff2)');
+font.load().then(() => {
+ document.fonts.add(font);
+ continueRender(handle);
+});
+```
+
+
+ - Install per font: `npm install @remotion/google-fonts` then import the specific font.
+ - Always call `loadFont()` at module level, not inside a component.
+ - For local fonts, place `.woff2` files in `/public` and use `delayRender` to ensure
+ they're loaded before the first frame renders.
+ - Use `fontFamily` from `loadFont()` in your style — don't hardcode the font name string.
+
+
+
+
+
+ Text Animations — typewriter, word reveals, character reveals
+
+```tsx
+// Typewriter — ALWAYS slice, never per-character opacity
+const charCount = Math.floor(
+ interpolate(frame, [0, fps * 3], [0, text.length], {
+ extrapolateRight: 'clamp',
+ })
+);
+const displayText = text.slice(0, charCount);
+
+// Word-by-word reveal
+const words = text.split(' ');
+const wordCount = Math.floor(
+ interpolate(frame, [0, fps * 3], [0, words.length], { extrapolateRight: 'clamp' })
+);
+const visibleWords = words.slice(0, wordCount).join(' ');
+
+// Character stagger with individual springs
+{text.split('').map((char, i) => {
+ const charOpacity = interpolate(frame - i * 2, [0, 10], [0, 1], {
+ extrapolateLeft: 'clamp',
+ extrapolateRight: 'clamp',
+ });
+ return {char};
+})}
+```
+
+
+ - For typewriter effects, always slice the string. NEVER use per-character opacity
+ to "reveal" — it creates layout shift and feels wrong.
+ - Word-by-word is better than char-by-char for readability in video.
+ - Avoid very slow character reveals — at 24fps, even 1 char/frame reads quickly.
+
+
+
+
+
+ Subtitles and Captions
+
+```tsx
+// Install: npm install @remotion/captions
+import { Caption, CaptionPage } from '@remotion/captions';
+import type { TranscriptionItem } from '@remotion/captions';
+
+// From a transcription API (Whisper, AssemblyAI, etc.)
+const transcription: TranscriptionItem[] = [
+ { text: 'Hello world', startMs: 0, endMs: 1500, confidence: 0.99 },
+ { text: 'How are you', startMs: 1600, endMs: 3000, confidence: 0.97 },
+];
+
+export const Subtitles: React.FC<{ transcription: TranscriptionItem[] }> = ({
+ transcription,
+}) => {
+ const frame = useCurrentFrame();
+ const { fps } = useVideoConfig();
+ const currentMs = (frame / fps) * 1000;
+
+ const currentItem = transcription.find(
+ (item) => currentMs >= item.startMs && currentMs <= item.endMs
+ );
+
+ return (
+
+ - Use `@remotion/captions` for word-level timing, SRT import, and TikTok-style highlights.
+ - Always convert frame to milliseconds: `(frame / fps) * 1000`.
+ - For word-by-word highlighting, iterate through `words` array from transcription
+ and highlight the word whose `startMs` ≤ currentMs ≤ `endMs`.
+ - Never hardcode caption timing — derive from transcription data or SRT.
+
+
+
+
+
+ Embedding Images
+
+```tsx
+import { Img, staticFile } from 'remotion';
+
+// Standard usage
+
+
+// Dynamic image sequence (frame-by-frame)
+
+
+// Conditional / data-driven
+})
+```
+
+
+ - Use `<Img>` NOT `<img>` — Remotion's version waits for the image to load.
+ - For animated GIFs, use `<Gif>` from `@remotion/gif`.
+ - `staticFile()` resolves paths relative to `/public`.
+ - Remote URLs are allowed but may slow rendering — prefer local assets.
+
+
+
+
+
+ Embedding Videos
+
+```tsx
+import { Video, staticFile, OffthreadVideo } from 'remotion';
+
+// Standard — synced to Remotion timeline
+
+
+// OffthreadVideo — better for complex videos, avoids browser decode issues
+
+ - `<Video>` is rendered in-browser via the video element — may have decode issues
+ with some codecs. Use `<OffthreadVideo>` for production renders.
+ - `startFrom` and `endAt` are in frames relative to the composition fps.
+ - `<Video>` inside a `<Sequence>` inherits the sequence's timing offset.
+ - Loop a video: `loop` prop on `<Video>`.
+
+
+
+
+
+ Charts and Data Visualization
+
+```tsx
+// Bar chart with staggered spring animation
+const STAGGER = 5;
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+{data.map((item, i) => {
+ const height = spring({
+ frame,
+ fps,
+ delay: i * STAGGER,
+ config: { damping: 200 },
+ });
+ return (
+
+ );
+})}
+
+// Animated SVG pie chart segment
+const progress = interpolate(frame, [0, fps * 2], [0, 1], {
+ extrapolateRight: 'clamp',
+ easing: Easing.out(Easing.cubic),
+});
+const circumference = 2 * Math.PI * radius;
+const segmentLength = (value / total) * circumference;
+const dashOffset = interpolate(progress, [0, 1], [segmentLength, 0]);
+
+
+ - Use HTML, SVG, or D3.js for charts — all work in Remotion.
+ - DISABLE any built-in animations from third-party chart libs — they cause flickering.
+ - Drive all chart animations from `useCurrentFrame()`.
+ - For `spring()` on bar heights, multiply by the target pixel height:
+ `height: spring(...) * maxBarHeight`.
+ - SVG pie: start at 12 o'clock with `rotate(-90 cx cy)`.
+
+
+
+
+
+ 3D Content with @remotion/three
+
+```tsx
+// Install: npx remotion add @remotion/three
+import { ThreeCanvas } from '@remotion/three';
+import { useVideoConfig, useCurrentFrame } from 'remotion';
+import { Sequence } from 'remotion';
+
+export const Scene3D: React.FC = () => {
+ const { width, height } = useVideoConfig();
+ const frame = useCurrentFrame();
+
+ // Drive rotation from frame — NOT from useFrame() or animation loops
+ const rotation = interpolate(frame, [0, 120], [0, Math.PI * 2]);
+
+ return (
+
+
+
+
+ );
+};
+
+// Sequence inside ThreeCanvas requires layout="none"
+
+
+
+
+
+
+```
+
+
+ - `<ThreeCanvas>` MUST have explicit `width` and `height` props.
+ - ALWAYS include lighting (`ambientLight` + `directionalLight` minimum).
+ - Shaders, models, and materials MUST NOT animate themselves (no `useFrame` loop).
+ Drive ALL animation from `useCurrentFrame()` and `interpolate()`/`spring()`.
+ - `<Sequence>` inside `<ThreeCanvas>` requires `layout="none"`.
+
+
+
+
+
+ Embedding Lottie Animations
+
+```tsx
+// Install: npm install @remotion/lottie
+import { Lottie, LottieAnimationData } from '@remotion/lottie';
+import animationData from './animation.json';
+
+export const LottieComp: React.FC = () => {
+ const { durationInFrames } = useVideoConfig();
+
+ return (
+
+ - Import Lottie JSON directly (not from a URL in most setups).
+ - `<Lottie>` syncs with Remotion's timeline automatically.
+ - `playbackRate` adjusts Lottie speed relative to Remotion's fps.
+ - Lottie animations that use custom fonts need those fonts loaded separately.
+
+
+
+
+
+ Displaying GIFs
+
+```tsx
+// Install: npm install @remotion/gif
+import { Gif } from '@remotion/gif';
+import { staticFile } from 'remotion';
+
+
+ - NEVER use `<img>` or `<Img>` for GIFs — they don't sync with the timeline.
+ - `<Gif>` loops by default and syncs with Remotion's frame counter.
+ - `fit` controls how the GIF fills its container.
+
+
+
+
+
+ Parametrizable Videos with Zod Schemas
+
+```tsx
+// Define schema for props — enables Remotion Studio GUI controls
+import { z } from 'zod';
+import { zColor } from '@remotion/zod-types';
+
+export const mySchema = z.object({
+ title: z.string().default('Hello World'),
+ color: zColor().default('#ffffff'),
+ duration: z.number().min(1).max(300).default(150),
+ showLogo: z.boolean().default(true),
+});
+
+type MyProps = z.infer;
+
+export const MyVideo: React.FC = ({ title, color, duration, showLogo }) => {
+ // ...
+};
+
+// Register with schema
+
+ - `zColor()` from `@remotion/zod-types` renders a color picker in the Studio.
+ - Schema enables passing props via CLI: `--props='{"title":"Hi"}'`.
+ - Use `schema.parse({})` to generate valid defaultProps automatically.
+ - Props are serialized to JSON — no functions, Dates, or class instances.
+
+
+
+
+
+ delayRender — blocking render for async operations
+
+```tsx
+import { delayRender, continueRender, cancelRender } from 'remotion';
+import { useEffect, useState } from 'react';
+
+export const AsyncComp: React.FC = () => {
+ const [data, setData] = useState(null);
+
+ // MUST be called synchronously — not inside useEffect
+ const [handle] = useState(() => delayRender('Fetching data'));
+
+ useEffect(() => {
+ fetch('/api/data')
+ .then(r => r.json())
+ .then(d => {
+ setData(d);
+ continueRender(handle);
+ })
+ .catch(err => {
+ cancelRender(err);
+ });
+ }, []);
+
+ if (!data) return null;
+
+ return
+ - `delayRender()` MUST be called synchronously (in component body or `useState` initializer).
+ - ALWAYS call `continueRender()` or `cancelRender()` — orphaned handles block rendering forever.
+ - Use the label string for debugging: `delayRender('Loading font')`, `delayRender('Fetching API')`.
+ - For maps (Mapbox), fonts, and external data — this is the required pattern.
+
+
+
+
+
+ Measuring Text Dimensions
+
+```tsx
+import { measureText, fitText } from '@remotion/layout-utils';
+
+// Measure a text string
+const { width } = measureText({
+ text: 'Hello World',
+ fontFamily: 'Arial',
+ fontSize: 48,
+ fontWeight: 'bold',
+});
+
+// Fit text to a container width
+const { fontSize } = fitText({
+ text: 'Dynamic Title That Fits',
+ fontFamily: 'Arial',
+ fontWeight: 'bold',
+ withinWidth: 800, // container width in px
+ textTransform: 'uppercase',
+});
+```
+
+
+ - Install: `npm install @remotion/layout-utils`
+ - `measureText` runs synchronously — call in render.
+ - `fitText` returns the largest font size that fits within the given width.
+ - Measured values are in pixels and depend on the font being loaded.
+
+
+
+
+
+ Measuring DOM Element Dimensions
+
+```tsx
+import { useRef, useState } from 'react';
+import { delayRender, continueRender } from 'remotion';
+
+export const AutoSizedText: React.FC = () => {
+ const ref = useRef(null);
+ const [height, setHeight] = useState(0);
+ const [handle] = useState(() => delayRender('Measuring DOM'));
+
+ // Use a callback ref to measure after mount
+ const measuredRef = (node: HTMLDivElement | null) => {
+ if (node) {
+ setHeight(node.getBoundingClientRect().height);
+ continueRender(handle);
+ }
+ };
+
+ return
+ - Use `delayRender` when you need DOM measurements before the first frame renders.
+ - Callback refs are more reliable than `useEffect` + `useRef` for first-paint measurements.
+ - Prefer `@remotion/layout-utils` for text measurement — no DOM needed.
+
+
+
+
+
+ Rendering Videos with Transparency
+
+```bash
+# Render to WebM with alpha channel (transparency)
+npx remotion render src/index.ts MyComp out/output.webm \
+ --codec=vp8 \
+ --pixel-format=yuva420p
+
+# For ProRes with alpha (macOS / Final Cut Pro)
+npx remotion render src/index.ts MyComp out/output.mov \
+ --codec=prores \
+ --prores-profile=4444
+```
+
+```tsx
+// In your composition — set background to transparent
+export const TransparentComp: React.FC = () => {
+ return (
+ // No background color on the root element
+
+
+ );
+};
+```
+
+
+ - WebM VP8/VP9 supports alpha — use `--pixel-format=yuva420p`.
+ - ProRes 4444 supports alpha — use `--prores-profile=4444`.
+ - H.264/MP4 does NOT support alpha — use WebM or ProRes instead.
+ - Do not set a background color on the root `<AbsoluteFill>` for transparent renders.
+
+
+
+
+
+ Animated Maps with Mapbox
+
+```tsx
+import mapboxgl from 'mapbox-gl';
+import { delayRender, continueRender, useCurrentFrame, useVideoConfig } from 'remotion';
+import { interpolate, Easing } from 'remotion';
+import { useEffect, useRef, useState } from 'react';
+
+mapboxgl.accessToken = process.env.MAPBOX_TOKEN!;
+
+export const MapAnimation: React.FC<{ route: [number, number][] }> = ({ route }) => {
+ const frame = useCurrentFrame();
+ const { fps, durationInFrames, width, height } = useVideoConfig();
+ const containerRef = useRef(null);
+ const [map, setMap] = useState(null);
+ const [handle] = useState(() => delayRender('Loading map'));
+
+ useEffect(() => {
+ if (!containerRef.current) return;
+
+ const m = new mapboxgl.Map({
+ container: containerRef.current,
+ style: 'mapbox://styles/mapbox/standard',
+ interactive: false, // REQUIRED — no user interaction during render
+ fadeDuration: 0, // REQUIRED — no fade-in transitions
+ center: route[0],
+ zoom: 12,
+ });
+
+ m.on('load', () => {
+ // Remove labels if desired
+ m.getStyle().layers.forEach(layer => {
+ if (layer.type === 'symbol') m.removeLayer(layer.id);
+ });
+
+ setMap(m);
+ continueRender(handle);
+ });
+ }, []);
+
+ // Animate camera from frame
+ useEffect(() => {
+ if (!map) return;
+ const progress = interpolate(frame, [0, durationInFrames - 1], [0, 1], {
+ extrapolateLeft: 'clamp', extrapolateRight: 'clamp',
+ easing: Easing.inOut(Easing.sin),
+ });
+ const idx = Math.floor(progress * (route.length - 1));
+ map.setCenter(route[idx]);
+ }, [frame, map]);
+
+ return (
+
+ );
+};
+```
+
+
+ - ALWAYS set `interactive: false` and `fadeDuration: 0` on the Mapbox instance.
+ - ALWAYS use `delayRender()` — map loads async.
+ - Container MUST have explicit `width`, `height`, and `position: 'absolute'`.
+ - Do NOT call `map.remove()` cleanup — causes issues with Remotion's renderer.
+ - For straight lines on a Mercator map: use linear interpolation between coords.
+ Do NOT use turf's `lineSliceAlong` — it uses great-circle math and appears curved.
+ - Drive ALL camera movement from `useCurrentFrame()` via `useEffect`.
+ - Default style: `mapbox://styles/mapbox/standard`.
+ - Render command for maps:
+ `npx remotion render --log=verbose --timeout=60000`
+
+
+
+
+
+ Light Leak Overlay Effects
+
+```tsx
+// Install: npm install @remotion/light-leaks
+import { LightLeak } from '@remotion/light-leaks';
+
+// Simple overlay — mix-blend-mode handles the compositing
+
+ - Use `mixBlendMode: 'screen'` for additive light leak effect.
+ - `speed` adjusts how fast the light leak moves (still frame-driven internally).
+ - Works best over dark backgrounds.
+
+
+
+
+
+ Trimming — cut beginning or end of animations
+
+```tsx
+// Trim the END: stop the animation at N frames, hold the final frame
+const ANIMATION_DURATION = 60;
+const clampedFrame = Math.min(frame, ANIMATION_DURATION - 1);
+const progress = interpolate(clampedFrame, [0, ANIMATION_DURATION - 1], [0, 1]);
+
+// Trim the START: skip first N frames of animation
+const TRIM_START = 20;
+const shiftedFrame = Math.max(0, frame - TRIM_START);
+const progress2 = interpolate(shiftedFrame, [0, 60], [0, 1], {
+ extrapolateRight: 'clamp',
+});
+
+// Or use Sequence's from prop to offset
+ {/* clips first 20 frames of child */}
+
+```
+
+
+ - `Math.min(frame, N-1)` freezes animation at last frame — use for holding the final state.
+ - `Math.max(0, frame - N)` delays start of animation by N frames.
+ - Wrapping in `<Sequence from={-N}>` clips the first N frames AND shifts the timeline.
+
+
+
+
+
+
+
+
+ - Restate the animation goal in one sentence.
+ - Identify which Remotion rules are relevant (from domain_knowledge above).
+ - Produce working, complete code — no "fill this in later" placeholders.
+ - Include: how to run it (`npx remotion preview` or render command).
+
+
+
+ - Default fps: 30, unless stated otherwise.
+ - Default resolution: 1920×1080, unless stated otherwise.
+ - Default duration: calculate from content, or use 150 frames (5s) if unspecified.
+ - If no package manager specified, use npm.
+ - All assets referenced exist in `/public` unless told otherwise.
+
+
+
+ Done when:
+ - All components are complete and renderable.
+ - No CSS animations or forbidden patterns present.
+ - TypeScript types are correct (no `any` unless genuinely necessary).
+ - `useCurrentFrame()` is the sole source of animation truth.
+ - Run/preview instructions are included.
+ - Edge cases (first frame, last frame, empty data) are handled.
+
+
+
+ For every Remotion task, deliver in this order:
+ 1. **Goal** — one sentence restating the objective.
+ 2. **Code** — complete, runnable components in fenced code blocks.
+ Always specify language: ```tsx
+ 3. **Composition Registration** — the Root.tsx entry if it's a new composition.
+ 4. **Run/Preview** — exact CLI commands.
+ 5. **Key Decisions** — brief notes on timing choices, package choices, etc.
+ 6. **Self-Reflection** — did this fully meet the goal? Any caveats?
+
+
+
+
+
+
+ - Use useCurrentFrame() for all animation values
+ - Use useVideoConfig() for fps/width/height/durationInFrames
+ - Always clamp interpolate() unless intentional overshoot
+ - Use <Img>, <Video>, <Audio> from 'remotion' — never native HTML elements
+ - Include extrapolateLeft/Right on every interpolate() call
+ - Use staticFile() for all /public assets
+ - Use delayRender/continueRender for any async operation
+
+
+
+ - CSS transitions or CSS animations (transition property, @keyframes)
+ - setTimeout / setInterval in components
+ - Date.now() for timing
+ - Math.random() without seeded PRNG
+ - Uncontrolled third-party animations (disable them; drive from frame)
+ - <img> for animated GIFs (use <Gif>)
+ - Inline styles with CSS transition property
+ - useFrame() from react-three-fiber for animation (use Remotion's frame)
+
+
+
+ 1. Remotion rendering correctness (frame-determinism) — HIGHEST
+ 2. TypeScript correctness
+ 3. Performance and memory efficiency
+ 4. Visual quality and design
+ 5. Code style preferences — LOWEST
+
+
+
+
+
+ - Never invent Remotion APIs that don't exist. If unsure, say so.
+ - If a feature requires a package not yet mentioned, explicitly state:
+ "Install: `npx remotion add @remotion/package-name`"
+ - Do not guess prop names — use the exact API signatures from the rules above.
+ - If a user requests something outside Remotion's capabilities (e.g., real-time
+ interaction during playback), explain the limitation clearly and offer alternatives.
+
+
+
+
+ After every response, briefly assess:
+ - Does every animation value flow from useCurrentFrame()? ✓/✗
+ - Are any CSS transitions or forbidden patterns present? ✓/✗
+ - Are interpolate() calls all clamped? ✓/✗
+ - Are async operations using delayRender/continueRender? ✓/✗
+ - Is the code immediately runnable without changes? ✓/✗
+
+
+
+```
+
+---
+
+## Usage Notes
+
+**To activate this prompt:**
+
+Paste the entire `` block as the system prompt in your agent (Claude Code, Cursor, OpenAI Assistants, etc.).
+
+**Key rules to drill in for prompting this agent:**
+
+When you ask for Remotion code, be specific about:
+- **Duration:** "5 seconds at 30fps" → agent will use `durationInFrames: 150`
+- **Easing:** "smooth ease-out" → agent will use `Easing.out(Easing.cubic)`
+- **Data:** "bar chart with this data array" → agent will disable third-party lib animations
+- **Audio:** "sync captions to this transcript" → agent will use `@remotion/captions`
+- **Entry point:** "this is a new composition" vs "add to existing Root.tsx"
+
+**Quick test to verify the agent is correctly loaded:**
+
+Ask: *"How do I create a fade-in in Remotion?"*
+
+If it mentions CSS transitions or React state → skill not loaded correctly.
+If it uses `interpolate(frame, [0, fps], [0, 1], { extrapolateRight: 'clamp' })` → working correctly.
+
+---
+
+## Complete Rule File Index (remotion-dev/skills)
+
+| Rule | Description | Package |
+|------|-------------|---------|
+| `animations.md` | interpolate, spring, stagger | `remotion` |
+| `sequencing.md` | Sequence, delay, trim | `remotion` |
+| `compositions.md` | Composition, Still, Folder | `remotion` |
+| `calculate-metadata.md` | Dynamic duration/dims | `remotion` |
+| `timing.md` | Easing curves | `remotion` |
+| `transitions.md` | TransitionSeries, slide/fade/wipe | `@remotion/transitions` |
+| `assets.md` | staticFile, Img, Video, Audio | `remotion` |
+| `audio.md` | trim, volume, speed | `remotion` |
+| `audio-visualization.md` | spectrum bars, waveforms | `@remotion/media-utils` |
+| `fonts.md` | Google Fonts, local fonts | `@remotion/google-fonts` |
+| `text-animations.md` | typewriter, word reveal | `remotion` |
+| `subtitles.md` | captions, SRT import | `@remotion/captions` |
+| `images.md` | Img, dynamic paths | `remotion` |
+| `videos.md` | Video, OffthreadVideo | `remotion` |
+| `charts.md` | bar, pie, line, SVG | `remotion` |
+| `3d.md` | ThreeCanvas, R3F | `@remotion/three` |
+| `lottie.md` | Lottie JSON animations | `@remotion/lottie` |
+| `gifs.md` | Gif component | `@remotion/gif` |
+| `parameters.md` | Zod schema, props | `zod`, `@remotion/zod-types` |
+| `measuring-text.md` | measureText, fitText | `@remotion/layout-utils` |
+| `measuring-dom-nodes.md` | DOM measurement | `remotion` |
+| `transparent-videos.md` | WebM alpha, ProRes | `remotion` |
+| `maps.md` | Mapbox animation | `mapbox-gl` |
+| `light-leaks.md` | LightLeak overlay | `@remotion/light-leaks` |
+| `trimming.md` | cut start/end | `remotion` |
+| `get-audio-duration.md` | audio duration in seconds | `@remotion/media-utils` |
+| `get-video-duration.md` | video duration in seconds | `@remotion/media-utils` |
+| `get-video-dimensions.md` | video width/height | `@remotion/media-utils` |
\ No newline at end of file
diff --git a/docs/protocols/2026-02-28-agent-first-ui-decisions.md b/docs/protocols/2026-02-28-agent-first-ui-decisions.md
new file mode 100644
index 0000000..2f20206
--- /dev/null
+++ b/docs/protocols/2026-02-28-agent-first-ui-decisions.md
@@ -0,0 +1,35 @@
+# Agent-First UI Decisions for Coordination Migration
+
+Date: 2026-02-28
+Status: Approved implementation defaults
+
+## Decision Summary
+
+1. Coordination writes are agent-first by default.
+2. Human operators supervise, comment, and override only when needed.
+3. Sessions conversation timeline remains a merged feed (activity + protocol + comments).
+
+## Interaction Ownership
+
+### Agent-owned by default
+
+- `SEND`, `READ`, `ACK`, `RESERVE`, `RELEASE`, `TAKEOVER` protocol events.
+- Routine reservation and handoff execution.
+
+### Human-owned by default
+
+- `bd comments` discussion entries.
+- Override intervention decisions (for blocked/conflict situations).
+
+## UI Behavior
+
+1. Conversation actions (`Seen`, `Accept`) emit `coord.v1` events via `/api/coord/events`.
+2. Comment composer includes explicit `Comment as` username field; value is persisted locally for convenience.
+3. Human comments use provided actor handle (instead of default email) when supplied.
+4. Incursions are computed from reservation projections and shown in sessions feed context.
+
+## Identity Policy
+
+1. Human comments should use user handle (for example `zenchant`) not raw email whenever available.
+2. Protocol events should use agent identity in `actor`.
+3. Timeline rendering must preserve actor attribution so human and agent actions stay distinguishable.
diff --git a/docs/protocols/2026-02-28-bb-deprecation-notes.md b/docs/protocols/2026-02-28-bb-deprecation-notes.md
new file mode 100644
index 0000000..3d2e33a
--- /dev/null
+++ b/docs/protocols/2026-02-28-bb-deprecation-notes.md
@@ -0,0 +1,24 @@
+# BB Deprecation Notes (Draft)
+
+Date: 2026-02-28
+Status: Legacy compatibility removed from migrated coordination path
+
+## Intent
+
+`bb` coordination paths are legacy compatibility behavior while `bd` audit/event protocol paths are rolled out.
+
+## Runtime Behavior
+
+- Sessions communication now uses `coord.v1` projections only.
+- Legacy mailbox fallback is removed from the migrated sessions path.
+
+## Removal Criteria
+
+1. Sessions and conversation flows operate correctly using only `coord.v1` projections.
+2. Read/ack actions are emitted via `/api/coord/events`.
+3. `npm run typecheck`, `npm run lint`, `npm run test` results are reviewed for migration-related regressions.
+
+## Post-Approval Work
+
+1. Update `skills/beadboard-driver` to `bd`-only commands and projection APIs.
+2. Remove deprecated route handlers that mutate legacy mailbox state.
diff --git a/docs/protocols/2026-02-28-bd-audit-coordination-schema.md b/docs/protocols/2026-02-28-bd-audit-coordination-schema.md
new file mode 100644
index 0000000..1c7e605
--- /dev/null
+++ b/docs/protocols/2026-02-28-bd-audit-coordination-schema.md
@@ -0,0 +1,120 @@
+# BD Audit Coordination Schema (Draft)
+
+Date: 2026-02-28
+Status: Draft for skill migration planning
+Scope: Replace `bb` coordination semantics with `bd`-native event/audit contracts
+
+Related protocol baseline:
+- `docs/protocols/operative-protocol-v1.md`
+
+## Intent
+
+Use `bd` as the only required system in agent work repos. Keep coordination state in append-only audit events, and keep human context in bead comments.
+
+Primary storage:
+- protocol state: `bd audit record --stdin`
+- lifecycle state: `bd update`, `bd close`, `bd agent state`, `bd agent heartbeat`
+- narrative context: `bd comments add`
+
+## Why Audit-First
+
+1. Append-only event log fits protocol timelines.
+2. Dolt history gives immutable version snapshots and diffability across event evolution.
+3. Frontend projections (inbox, reservation map, takeover eligibility) can be derived deterministically from event history.
+
+## Event Envelope (v1)
+
+Every coordination event SHOULD use this envelope (JSON sent through `bd audit record --stdin`):
+
+```json
+{
+ "version": "coord.v1",
+ "kind": "coord_event",
+ "issue_id": "bb-123",
+ "actor": "amber-otter",
+ "timestamp": "2026-02-28T18:00:00.000Z",
+ "data": {
+ "event_type": "RESERVE",
+ "event_id": "evt_01JN6Y1Q7R80E8P6K1Q5",
+ "project_root": "/abs/path/to/repo",
+ "to_agent": "cobalt-harbor",
+ "scope": "src/lib/*",
+ "state": "unread",
+ "takeover_mode": "none",
+ "reason": "",
+ "payload": {}
+ }
+}
+```
+
+Notes:
+- `kind` remains compatible with `bd audit` entry typing.
+- protocol-specific fields live under `data`.
+- `event_id` MUST be globally unique and stable for dedupe.
+
+## Canonical Event Types
+
+Required for parity with current `bb` behavior:
+1. `SEND`: directed message created (`to_agent` required, `state=unread`)
+2. `READ`: message seen (`event_ref` to prior `SEND`)
+3. `ACK`: message accepted (`event_ref` to prior `SEND`)
+4. `RESERVE`: scope reservation created
+5. `RELEASE`: scope reservation released
+6. `TAKEOVER`: stale/evicted reservation force-acquired
+7. `RESUME`: identity adoption event
+8. `BLOCKED`: explicit blocker signal
+9. `HANDOFF`: explicit transfer signal
+10. `INCURSION`: overlap warning signal
+
+## Required Fields by Event
+
+Shared required fields:
+- `event_type`
+- `event_id`
+- `project_root`
+- `issue_id`
+- `actor`
+- `timestamp`
+
+Extra required fields:
+- `SEND`: `to_agent`, `payload.subject`, `payload.body`
+- `READ`: `event_ref`
+- `ACK`: `event_ref`
+- `RESERVE`: `scope`, `payload.ttl_minutes`
+- `RELEASE`: `scope`
+- `TAKEOVER`: `scope`, `takeover_mode` (`stale` | `evicted`), `reason`
+- `RESUME`: `payload.prior_agent`, `reason` (`uncommitted_scope` | `in_progress_ownership`)
+- `BLOCKED`: `to_agent`, `payload.blocker`, `payload.requested_action`
+- `HANDOFF`: `to_agent`, `payload.summary`, `payload.next_action`
+- `INCURSION`: `scope`, `payload.incursion_kind` (`exact` | `partial`), `payload.owner_liveness`
+
+## Derivation Rules (Frontend/API)
+
+Inbox projection:
+- unread: `SEND` with no later `READ`/`ACK` on same `event_id`
+- read: `READ` exists, no later `ACK`
+- acked: `ACK` exists
+
+Reservation projection:
+- active reservation = latest event for `(project_root, scope)` is `RESERVE` or `TAKEOVER` and not superseded by `RELEASE`
+- owner liveness from `bd agent heartbeat/state`
+
+Takeover policy:
+- owner active: deny takeover
+- owner stale: allow only explicit stale takeover mode
+- owner evicted: allow takeover and mark prior reservation expired in projection
+
+## Dolt Considerations
+
+1. Never rewrite prior protocol events; only append.
+2. Treat projections as computed views, never source of truth.
+3. Use Dolt history for postmortems (`bd history`/`bd diff`) against protocol incidents.
+4. Keep schema versioned (`coord.v1` -> future upgrades by additive fields and new event types).
+
+## Skill Migration Guidance (Later Work)
+
+When updating `skills/beadboard-driver`, use this contract:
+1. Replace `bb agent send/inbox/read/ack` with `bd audit` event writes + API-derived inbox reads.
+2. Replace `bb reserve/release/status` with `bd audit` reservation events + API overlap/liveness checks.
+3. Keep `bd` lifecycle commands unchanged.
+4. Keep human summaries in `bd comments` for operator readability.
diff --git a/docs/protocols/operative-protocol-v1.md b/docs/protocols/operative-protocol-v1.md
index 73b0c23..a8522e9 100644
--- a/docs/protocols/operative-protocol-v1.md
+++ b/docs/protocols/operative-protocol-v1.md
@@ -1,7 +1,7 @@
# Operative Protocol v1 (Session Constitution)
Date: 2026-02-14
-Status: Approved for implementation
+Status: Approved for implementation (superseded for migration planning by `docs/protocols/2026-02-28-bd-audit-coordination-schema.md`)
Scope: `bb-u6f.6.1`
Applies to: `bb-u6f.6.2`, `bb-u6f.6.3`, `bb-u6f.6.4`, `bb-u6f.6.5`
@@ -15,6 +15,10 @@ Boundaries:
3. No direct writes to `.beads/issues.jsonl`.
4. User-facing labels must stay plain language.
+Migration note:
+1. New work should target the `coord.v1` `bd audit` event model documented in `docs/protocols/2026-02-28-bd-audit-coordination-schema.md`.
+2. `bb` coordination semantics are legacy compatibility behavior pending removal after migration sign-off.
+
## 2. Normative Language
1. MUST: required behavior.
diff --git a/eslint.config.mjs b/eslint.config.mjs
index 29a92b5..5ae70d1 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -14,6 +14,7 @@ const eslintConfig = [
'.next/**',
'.agents/**',
'skills/**',
+ 'reference/**',
'next-env.d.ts',
],
},
diff --git a/agent-help.txt b/help/cli/agent-help.txt
similarity index 100%
rename from agent-help.txt
rename to help/cli/agent-help.txt
diff --git a/help/cli/bd-branch-help.txt b/help/cli/bd-branch-help.txt
new file mode 100644
index 0000000..db99a03
--- /dev/null
+++ b/help/cli/bd-branch-help.txt
@@ -0,0 +1,31 @@
+List all branches or create a new branch.
+
+This command requires the Dolt storage backend. Without arguments,
+it lists all branches. With an argument, it creates a new branch.
+
+Examples:
+ bd branch # List all branches
+ bd branch feature-xyz # Create a new branch named feature-xyz
+
+Usage:
+ bd branch [name] [flags]
+
+Flags:
+ -h, --help help for branch
+
+Global Flags:
+ --actor string Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
+ --allow-stale Allow operations on potentially stale data (skip staleness check)
+ --db string Database path (default: auto-discover .beads/*.db)
+ --dolt-auto-commit string Dolt backend: auto-commit after write commands (off|on). Default from config key dolt.auto-commit
+ --json Output in JSON format
+ --lock-timeout duration SQLite busy timeout (0 = fail immediately if locked) (default 30s)
+ --no-auto-flush Disable automatic JSONL sync after CRUD operations
+ --no-auto-import Disable automatic JSONL import when newer than DB
+ --no-daemon Force direct storage mode, bypass daemon if running
+ --no-db Use no-db mode: load from JSONL, no SQLite
+ --profile Generate CPU profile for performance analysis
+ -q, --quiet Suppress non-essential output (errors only)
+ --readonly Read-only mode: block write operations (for worker sandboxes)
+ --sandbox Sandbox mode: disables daemon and auto-sync
+ -v, --verbose Enable verbose/debug output
diff --git a/help/cli/bd-config-list.txt b/help/cli/bd-config-list.txt
new file mode 100644
index 0000000..e69de29
diff --git a/help/cli/bd-create-help.txt b/help/cli/bd-create-help.txt
new file mode 100644
index 0000000..60d47ca
--- /dev/null
+++ b/help/cli/bd-create-help.txt
@@ -0,0 +1,61 @@
+Create a new issue (or multiple issues from markdown file)
+
+Usage:
+ bd create [title] [flags]
+
+Aliases:
+ create, new
+
+Flags:
+ --acceptance string Acceptance criteria
+ --agent-rig string Agent's rig name (requires --type=agent)
+ --append-notes string Append to existing notes (with newline separator)
+ -a, --assignee string Assignee
+ --body-file string Read description from file (use - for stdin)
+ --defer string Defer until date (issue hidden from bd ready until then). Same formats as --due
+ --deps strings Dependencies in format 'type:id' or 'id' (e.g., 'discovered-from:bd-20,blocks:bd-15' or 'bd-20')
+ -d, --description string Issue description
+ --design string Design notes
+ --dry-run Preview what would be created without actually creating
+ --due string Due date/time. Formats: +6h, +1d, +2w, tomorrow, next monday, 2025-01-15
+ --ephemeral Create as ephemeral (short-lived, subject to TTL compaction)
+ -e, --estimate int Time estimate in minutes (e.g., 60 for 1 hour)
+ --event-actor string Entity URI who caused this event (requires --type=event)
+ --event-category string Event category (e.g., patrol.muted, agent.started) (requires --type=event)
+ --event-payload string Event-specific JSON data (requires --type=event)
+ --event-target string Entity URI or bead ID affected (requires --type=event)
+ --external-ref string External reference (e.g., 'gh-9', 'jira-ABC')
+ -f, --file string Create multiple issues from markdown file
+ --force Force creation even if prefix doesn't match database prefix
+ -h, --help help for create
+ --id string Explicit issue ID (e.g., 'bd-42' for partitioning)
+ -l, --labels strings Labels (comma-separated)
+ --metadata string Set custom metadata (JSON string or @file.json to read from file)
+ --mol-type string Molecule type: swarm (multi-polecat), patrol (recurring ops), work (default)
+ --no-inherit-labels Don't inherit labels from parent issue
+ --notes string Additional notes
+ --parent string Parent issue ID for hierarchical child (e.g., 'bd-a3f8e9')
+ --prefix string Create issue in rig by prefix (e.g., --prefix bd- or --prefix bd or --prefix beads)
+ -p, --priority string Priority (0-4 or P0-P4, 0=highest) (default "2")
+ --repo string Target repository for issue (overrides auto-routing)
+ --rig string Create issue in a different rig (e.g., --rig beads)
+ --silent Output only the issue ID (for scripting)
+ --spec-id string Link to specification document
+ --title string Issue title (alternative to positional argument)
+ -t, --type string Issue type (bug|feature|task|epic|chore|decision); custom types require types.custom config; aliases: enhancement/feat→feature, dec/adr→decision (default "task")
+ --validate Validate description contains required sections for issue type
+ --waits-for string Spawner issue ID to wait for (creates waits-for dependency for fanout gate)
+ --waits-for-gate string Gate type: all-children (wait for all) or any-children (wait for first) (default "all-children")
+ --wisp-type string Wisp type for TTL-based compaction: heartbeat, ping, patrol, gc_report, recovery, error, escalation
+
+Global Flags:
+ --actor string Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
+ --allow-stale Allow operations on potentially stale data (skip staleness check)
+ --db string Database path (default: auto-discover .beads/*.db)
+ --dolt-auto-commit string Dolt auto-commit policy (off|on|batch). 'on': commit after each write. 'batch': defer commits to bd sync / bd dolt commit; uncommitted changes persist in the working set until then. SIGTERM/SIGHUP flush pending batch commits. Default: off. Override via config key dolt.auto-commit
+ --json Output in JSON format
+ --profile Generate CPU profile for performance analysis
+ -q, --quiet Suppress non-essential output (errors only)
+ --readonly Read-only mode: block write operations (for worker sandboxes)
+ --sandbox Sandbox mode: disables auto-sync
+ -v, --verbose Enable verbose/debug output
diff --git a/help/cli/bd-daemon-help.txt b/help/cli/bd-daemon-help.txt
new file mode 100644
index 0000000..a65d869
--- /dev/null
+++ b/help/cli/bd-daemon-help.txt
@@ -0,0 +1,75 @@
+Manage the background daemon that automatically syncs issues with git remote.
+
+The daemon will:
+- Poll for changes at configurable intervals (default: 5 seconds)
+- Export pending database changes to JSONL
+- Auto-commit changes if --auto-commit flag set
+- Auto-push commits if --auto-push flag set
+- Pull remote changes periodically
+- Auto-import when remote changes detected
+
+Common operations:
+ bd daemon start Start the daemon (background)
+ bd daemon start --foreground Start in foreground (for systemd/supervisord)
+ bd daemon stop Stop current workspace daemon
+ bd daemon status Show daemon status
+ bd daemon status --all Show all daemons with health check
+ bd daemon logs View daemon logs
+ bd daemon restart Restart daemon
+ bd daemon killall Stop all running daemons
+
+Run 'bd daemon --help' to see all subcommands.
+
+Usage:
+ bd daemon [flags]
+ bd daemon [command]
+
+Available Commands:
+ health Check health of all bd daemons
+ killall Stop all running bd daemons
+ list List all running bd daemons
+ logs View logs for a specific bd daemon
+ restart Restart a specific bd daemon
+ start Start the background daemon
+ status Show daemon status
+ stop Stop a specific bd daemon
+
+Flags:
+ --auto-commit Automatically commit changes
+ --auto-pull Automatically pull from remote (default: true when sync.branch configured)
+ --auto-push Automatically push commits
+ --federation Enable federation mode (runs dolt sql-server with remotesapi)
+ --federation-port int MySQL port for federation mode dolt sql-server (default 3307)
+ --foreground Run in foreground (don't daemonize)
+ --health Check daemon health (deprecated: use 'bd daemon status --all')
+ -h, --help help for daemon
+ --interval duration Sync check interval (default 5s)
+ --json Output JSON format
+ --local Run in local-only mode (no git required, no sync)
+ --log string Log file path (default: .beads/daemon.log)
+ --log-json Output logs in JSON format (structured logging)
+ --log-level string Log level (debug, info, warn, error) (default "info")
+ --metrics Show detailed daemon metrics
+ --remotesapi-port int remotesapi port for peer-to-peer sync in federation mode (default 8080)
+ --start Start the daemon (deprecated: use 'bd daemon start')
+ --status Show daemon status (deprecated: use 'bd daemon status')
+ --stop Stop running daemon (deprecated: use 'bd daemon stop')
+ --stop-all Stop all running bd daemons (deprecated: use 'bd daemon killall')
+
+Global Flags:
+ --actor string Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
+ --allow-stale Allow operations on potentially stale data (skip staleness check)
+ --db string Database path (default: auto-discover .beads/*.db)
+ --dolt-auto-commit string Dolt backend: auto-commit after write commands (off|on). Default from config key dolt.auto-commit
+ --lock-timeout duration SQLite busy timeout (0 = fail immediately if locked) (default 30s)
+ --no-auto-flush Disable automatic JSONL sync after CRUD operations
+ --no-auto-import Disable automatic JSONL import when newer than DB
+ --no-daemon Force direct storage mode, bypass daemon if running
+ --no-db Use no-db mode: load from JSONL, no SQLite
+ --profile Generate CPU profile for performance analysis
+ -q, --quiet Suppress non-essential output (errors only)
+ --readonly Read-only mode: block write operations (for worker sandboxes)
+ --sandbox Sandbox mode: disables daemon and auto-sync
+ -v, --verbose Enable verbose/debug output
+
+Use "bd daemon [command] --help" for more information about a command.
diff --git a/help/cli/bd-diff-help.txt b/help/cli/bd-diff-help.txt
new file mode 100644
index 0000000..e7b63a0
--- /dev/null
+++ b/help/cli/bd-diff-help.txt
@@ -0,0 +1,34 @@
+Show the differences in issues between two commits or branches.
+
+This command requires the Dolt storage backend. The refs can be:
+- Commit hashes (e.g., abc123def)
+- Branch names (e.g., main, feature-branch)
+- Special refs like HEAD, HEAD~1
+
+Examples:
+ bd diff main feature-branch # Compare main to feature branch
+ bd diff HEAD~5 HEAD # Show changes in last 5 commits
+ bd diff abc123 def456 # Compare two specific commits
+
+Usage:
+ bd diff [flags]
+
+Flags:
+ -h, --help help for diff
+
+Global Flags:
+ --actor string Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
+ --allow-stale Allow operations on potentially stale data (skip staleness check)
+ --db string Database path (default: auto-discover .beads/*.db)
+ --dolt-auto-commit string Dolt backend: auto-commit after write commands (off|on). Default from config key dolt.auto-commit
+ --json Output in JSON format
+ --lock-timeout duration SQLite busy timeout (0 = fail immediately if locked) (default 30s)
+ --no-auto-flush Disable automatic JSONL sync after CRUD operations
+ --no-auto-import Disable automatic JSONL import when newer than DB
+ --no-daemon Force direct storage mode, bypass daemon if running
+ --no-db Use no-db mode: load from JSONL, no SQLite
+ --profile Generate CPU profile for performance analysis
+ -q, --quiet Suppress non-essential output (errors only)
+ --readonly Read-only mode: block write operations (for worker sandboxes)
+ --sandbox Sandbox mode: disables daemon and auto-sync
+ -v, --verbose Enable verbose/debug output
diff --git a/help/cli/bd-dolt-help.txt b/help/cli/bd-dolt-help.txt
new file mode 100644
index 0000000..f005dc8
--- /dev/null
+++ b/help/cli/bd-dolt-help.txt
@@ -0,0 +1,75 @@
+Configure and manage Dolt database settings and server lifecycle.
+
+Beads uses a dolt sql-server for all database operations. The server is
+auto-started transparently when needed. Use these commands for explicit
+control or diagnostics.
+
+Server lifecycle:
+ bd dolt start Start the Dolt server for this project
+ bd dolt stop Stop the Dolt server for this project
+ bd dolt status Show Dolt server status
+
+Configuration:
+ bd dolt show Show current Dolt configuration with connection test
+ bd dolt set Set a configuration value
+ bd dolt test Test server connection
+
+Version control:
+ bd dolt commit Commit pending changes
+ bd dolt push Push commits to Dolt remote
+ bd dolt pull Pull commits from Dolt remote
+
+Remote management:
+ bd dolt remote add Add a Dolt remote
+ bd dolt remote list List configured remotes
+ bd dolt remote remove Remove a Dolt remote
+
+Configuration keys for 'bd dolt set':
+ database Database name (default: issue prefix or "beads")
+ host Server host (default: 127.0.0.1)
+ port Server port (auto-detected; override with bd dolt set port )
+ user MySQL user (default: root)
+ data-dir Custom dolt data directory (absolute path; default: .beads/dolt)
+
+Flags for 'bd dolt set':
+ --update-config Also write to config.yaml for team-wide defaults
+
+Examples:
+ bd dolt set database myproject
+ bd dolt set host 192.168.1.100 --update-config
+ bd dolt set data-dir /home/user/.beads-dolt/myproject
+ bd dolt test
+
+Usage:
+ bd dolt [command]
+
+Available Commands:
+ clean-databases Drop stale test/polecat databases from the Dolt server
+ commit Create a Dolt commit from pending changes
+ killall Kill all orphan Dolt server processes
+ pull Pull commits from Dolt remote
+ push Push commits to Dolt remote
+ remote Manage Dolt remotes
+ set Set a Dolt configuration value
+ show Show current Dolt configuration with connection status
+ start Start the Dolt SQL server for this project
+ status Show Dolt server status
+ stop Stop the Dolt SQL server for this project
+ test Test connection to Dolt server
+
+Flags:
+ -h, --help help for dolt
+
+Global Flags:
+ --actor string Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
+ --allow-stale Allow operations on potentially stale data (skip staleness check)
+ --db string Database path (default: auto-discover .beads/*.db)
+ --dolt-auto-commit string Dolt auto-commit policy (off|on|batch). 'on': commit after each write. 'batch': defer commits to bd sync / bd dolt commit; uncommitted changes persist in the working set until then. SIGTERM/SIGHUP flush pending batch commits. Default: off. Override via config key dolt.auto-commit
+ --json Output in JSON format
+ --profile Generate CPU profile for performance analysis
+ -q, --quiet Suppress non-essential output (errors only)
+ --readonly Read-only mode: block write operations (for worker sandboxes)
+ --sandbox Sandbox mode: disables auto-sync
+ -v, --verbose Enable verbose/debug output
+
+Use "bd dolt [command] --help" for more information about a command.
diff --git a/help/cli/bd-list-help.txt b/help/cli/bd-list-help.txt
new file mode 100644
index 0000000..0fc51d0
--- /dev/null
+++ b/help/cli/bd-list-help.txt
@@ -0,0 +1,74 @@
+List issues
+
+Usage:
+ bd list [flags]
+
+Flags:
+ --all Show all issues including closed (overrides default filter)
+ -a, --assignee string Filter by assignee
+ --closed-after string Filter issues closed after date (YYYY-MM-DD or RFC3339)
+ --closed-before string Filter issues closed before date (YYYY-MM-DD or RFC3339)
+ --created-after string Filter issues created after date (YYYY-MM-DD or RFC3339)
+ --created-before string Filter issues created before date (YYYY-MM-DD or RFC3339)
+ --defer-after string Filter issues deferred after date (supports relative: +6h, tomorrow)
+ --defer-before string Filter issues deferred before date (supports relative: +6h, tomorrow)
+ --deferred Show only issues with defer_until set
+ --desc-contains string Filter by description substring (case-insensitive)
+ --due-after string Filter issues due after date (supports relative: +6h, tomorrow)
+ --due-before string Filter issues due before date (supports relative: +6h, tomorrow)
+ --empty-description Filter issues with empty or missing description
+ --filter-parent string Alias for --parent
+ --format string Output format: 'digraph' (for golang.org/x/tools/cmd/digraph), 'dot' (Graphviz), or Go template
+ -h, --help help for list
+ --id string Filter by specific issue IDs (comma-separated, e.g., bd-1,bd-5,bd-10)
+ --include-gates Include gate issues in output (normally hidden)
+ --include-templates Include template molecules in output
+ -l, --label strings Filter by labels (AND: must have ALL). Can combine with --label-any
+ --label-any strings Filter by labels (OR: must have AT LEAST ONE). Can combine with --label
+ --label-pattern string Filter by label glob pattern (e.g., 'tech-*' matches tech-debt, tech-legacy)
+ --label-regex string Filter by label regex pattern (e.g., 'tech-(debt|legacy)')
+ -n, --limit int Limit results (default 50, use 0 for unlimited) (default 50)
+ --long Show detailed multi-line output for each issue
+ --mol-type string Filter by molecule type: swarm, patrol, or work
+ --no-assignee Filter issues with no assignee
+ --no-labels Filter issues with no labels
+ --no-pager Disable pager output
+ --no-pinned Exclude pinned issues
+ --notes-contains string Filter by notes substring (case-insensitive)
+ --overdue Show only issues with due_at in the past (not closed)
+ --parent string Filter by parent issue ID (shows children of specified issue)
+ --pinned Show only pinned issues
+ --pretty Display issues in a tree format with status/priority symbols
+ -p, --priority string Priority (0-4 or P0-P4, 0=highest)
+ --priority-max string Filter by maximum priority (inclusive, 0-4 or P0-P4)
+ --priority-min string Filter by minimum priority (inclusive, 0-4 or P0-P4)
+ --ready Show only ready issues (status=open, excludes hooked/in_progress/blocked/deferred)
+ -r, --reverse Reverse sort order
+ --sort string Sort by field: priority, created, updated, closed, status, id, title, type, assignee
+ --spec string Filter by spec_id prefix
+ -s, --status string Filter by status (open, in_progress, blocked, deferred, closed)
+ --title string Filter by title text (case-insensitive substring match)
+ --title-contains string Filter by title substring (case-insensitive)
+ --tree Alias for --pretty: hierarchical tree format
+ -t, --type string Filter by type (bug, feature, task, epic, chore, merge-request, molecule, gate, convoy). Aliases: mr→merge-request, feat→feature, mol→molecule
+ --updated-after string Filter issues updated after date (YYYY-MM-DD or RFC3339)
+ --updated-before string Filter issues updated before date (YYYY-MM-DD or RFC3339)
+ -w, --watch Watch for changes and auto-update display (implies --pretty)
+ --wisp-type string Filter by wisp type: heartbeat, ping, patrol, gc_report, recovery, error, escalation
+
+Global Flags:
+ --actor string Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
+ --allow-stale Allow operations on potentially stale data (skip staleness check)
+ --db string Database path (default: auto-discover .beads/*.db)
+ --dolt-auto-commit string Dolt backend: auto-commit after write commands (off|on). Default from config key dolt.auto-commit
+ --json Output in JSON format
+ --lock-timeout duration SQLite busy timeout (0 = fail immediately if locked) (default 30s)
+ --no-auto-flush Disable automatic JSONL sync after CRUD operations
+ --no-auto-import Disable automatic JSONL import when newer than DB
+ --no-daemon Force direct storage mode, bypass daemon if running
+ --no-db Use no-db mode: load from JSONL, no SQLite
+ --profile Generate CPU profile for performance analysis
+ -q, --quiet Suppress non-essential output (errors only)
+ --readonly Read-only mode: block write operations (for worker sandboxes)
+ --sandbox Sandbox mode: disables daemon and auto-sync
+ -v, --verbose Enable verbose/debug output
diff --git a/help/cli/bd-query-help.txt b/help/cli/bd-query-help.txt
new file mode 100644
index 0000000..3b40fdb
--- /dev/null
+++ b/help/cli/bd-query-help.txt
@@ -0,0 +1,85 @@
+Query issues using a simple query language that supports compound filters,
+boolean operators, and date-relative expressions.
+
+The query language enables complex filtering that would otherwise require
+multiple flags or piping through jq.
+
+Syntax:
+ field=value Equality comparison
+ field!=value Inequality comparison
+ field>value Greater than
+ field>=value Greater than or equal
+ field1"
+ bd query "status=open AND priority<=2 AND updated>7d"
+ bd query "(status=open OR status=blocked) AND priority<2"
+ bd query "type=bug AND label=urgent"
+ bd query "NOT status=closed"
+ bd query "assignee=none AND type=task"
+ bd query "created>30d AND status!=closed"
+ bd query "label=frontend OR label=backend"
+ bd query "title=authentication AND priority=0"
+
+Usage:
+ bd query [expression] [flags]
+
+Flags:
+ -a, --all Include closed issues (default: exclude closed)
+ -h, --help help for query
+ -n, --limit int Limit results (default: 50, 0 = unlimited) (default 50)
+ --long Show detailed multi-line output for each issue
+ --parse-only Only parse the query and show the AST (for debugging)
+ -r, --reverse Reverse sort order
+ --sort string Sort by field: priority, created, updated, closed, status, id, title, type, assignee
+
+Global Flags:
+ --actor string Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
+ --allow-stale Allow operations on potentially stale data (skip staleness check)
+ --db string Database path (default: auto-discover .beads/*.db)
+ --dolt-auto-commit string Dolt backend: auto-commit after write commands (off|on). Default from config key dolt.auto-commit
+ --json Output in JSON format
+ --lock-timeout duration SQLite busy timeout (0 = fail immediately if locked) (default 30s)
+ --no-auto-flush Disable automatic JSONL sync after CRUD operations
+ --no-auto-import Disable automatic JSONL import when newer than DB
+ --no-daemon Force direct storage mode, bypass daemon if running
+ --no-db Use no-db mode: load from JSONL, no SQLite
+ --profile Generate CPU profile for performance analysis
+ -q, --quiet Suppress non-essential output (errors only)
+ --readonly Read-only mode: block write operations (for worker sandboxes)
+ --sandbox Sandbox mode: disables daemon and auto-sync
+ -v, --verbose Enable verbose/debug output
diff --git a/help/cli/bd-vc-help.txt b/help/cli/bd-vc-help.txt
new file mode 100644
index 0000000..e9382af
--- /dev/null
+++ b/help/cli/bd-vc-help.txt
@@ -0,0 +1,38 @@
+Version control operations for the beads database.
+
+These commands require the Dolt storage backend. They provide git-like
+version control for your issue data, including branching, merging, and
+viewing history.
+
+Note: 'bd history', 'bd diff', and 'bd branch' also work for quick access.
+This subcommand provides additional operations like merge and commit.
+
+Usage:
+ bd vc [command]
+
+Available Commands:
+ commit Create a commit with all staged changes
+ merge Merge a branch into the current branch
+ status Show current branch and uncommitted changes
+
+Flags:
+ -h, --help help for vc
+
+Global Flags:
+ --actor string Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
+ --allow-stale Allow operations on potentially stale data (skip staleness check)
+ --db string Database path (default: auto-discover .beads/*.db)
+ --dolt-auto-commit string Dolt backend: auto-commit after write commands (off|on). Default from config key dolt.auto-commit
+ --json Output in JSON format
+ --lock-timeout duration SQLite busy timeout (0 = fail immediately if locked) (default 30s)
+ --no-auto-flush Disable automatic JSONL sync after CRUD operations
+ --no-auto-import Disable automatic JSONL import when newer than DB
+ --no-daemon Force direct storage mode, bypass daemon if running
+ --no-db Use no-db mode: load from JSONL, no SQLite
+ --profile Generate CPU profile for performance analysis
+ -q, --quiet Suppress non-essential output (errors only)
+ --readonly Read-only mode: block write operations (for worker sandboxes)
+ --sandbox Sandbox mode: disables daemon and auto-sync
+ -v, --verbose Enable verbose/debug output
+
+Use "bd vc [command] --help" for more information about a command.
diff --git a/help.txt b/help/cli/bd_help.txt
similarity index 100%
rename from help.txt
rename to help/cli/bd_help.txt
diff --git a/epic-help.txt b/help/cli/epic-help.txt
similarity index 100%
rename from epic-help.txt
rename to help/cli/epic-help.txt
diff --git a/epic.txt b/help/cli/epic.txt
similarity index 100%
rename from epic.txt
rename to help/cli/epic.txt
diff --git a/help/cli/help.txt b/help/cli/help.txt
new file mode 100644
index 0000000..b6fcfc5
--- /dev/null
+++ b/help/cli/help.txt
@@ -0,0 +1,136 @@
+Issues chained together like beads. A lightweight issue tracker with first-class dependency support.
+
+Usage:
+ bd [flags]
+ bd [command]
+
+Maintenance:
+ rename-prefix Rename the issue prefix for all issues in the database
+ repair Repair corrupted database by cleaning orphaned references
+ resolve-conflicts Resolve git merge conflicts in JSONL files
+
+Integrations & Advanced:
+Working With Issues:
+ children List child beads of a parent
+ close Close one or more issues
+ comments View or manage comments on an issue
+ create Create a new issue (or multiple issues from markdown file)
+ create-form Create a new issue using an interactive form
+ delete Delete one or more issues and clean up references
+ edit Edit an issue field in $EDITOR
+ gate Manage async coordination gates
+ label Manage issue labels
+ list List issues
+ merge-slot Manage merge-slot gates for serialized conflict resolution
+ move Move an issue to a different rig with dependency remapping
+ promote Promote a wisp to a permanent bead
+ q Quick capture: create issue and output only ID
+ query Query issues using a simple query language
+ refile Move an issue to a different rig
+ reopen Reopen one or more closed issues
+ search Search issues by text query
+ set-state Set operational state (creates event + updates label)
+ show Show issue details
+ state Query the current value of a state dimension
+ todo Manage TODO items (convenience wrapper for task issues)
+ update Update one or more issues
+
+Views & Reports:
+ activity Show real-time molecule state feed
+ count Count issues matching filters
+ diff Show changes between two commits or branches (requires Dolt backend)
+ find-duplicates Find semantically similar issues using text analysis or AI
+ history Show version history for an issue (requires Dolt backend)
+ lint Check issues for missing template sections
+ stale Show stale issues (not updated recently)
+ status Show issue database overview and statistics
+ types List valid issue types
+
+Dependencies & Structure:
+ dep Manage dependencies
+ duplicate Mark an issue as a duplicate of another
+ duplicates Find and optionally merge duplicate issues
+ epic Epic management commands
+ graph Display issue dependency graph
+ supersede Mark an issue as superseded by a newer one
+ swarm Swarm management for structured epics
+
+Sync & Data:
+ branch List or create branches (requires Dolt backend)
+ daemon Manage background sync daemon
+ export Export issues to JSONL or Obsidian format
+ federation Manage peer-to-peer federation (requires CGO)
+ import Import issues from JSONL format
+ merge Git merge driver for beads JSONL files
+ restore Restore full history of a compacted issue from git
+ sync Export database to JSONL (sync with git)
+ vc Version control operations (requires Dolt backend)
+
+Setup & Configuration:
+ backend Manage storage backend configuration
+ config Manage configuration settings
+ hooks Manage git hooks for bd auto-sync
+ human Show essential commands for human users
+ info Show database and daemon information
+ init Initialize bd in the current directory
+ kv Key-value store commands
+ onboard Display minimal snippet for AGENTS.md
+ prime Output AI-optimized workflow context
+ quickstart Quick start guide for bd
+ setup Setup integration with AI editors
+ where Show active beads location
+
+Maintenance:
+ doctor Check and fix beads installation health (start here)
+ migrate Database migration commands
+ preflight Show PR readiness checklist
+ upgrade Check and manage bd version upgrades
+ worktree Manage git worktrees for parallel development
+
+Integrations & Advanced:
+ admin Administrative commands for database maintenance
+ jira Jira integration commands
+ linear Linear integration commands
+ repo Manage multiple repository configuration
+
+Additional Commands:
+ agent Manage agent bead state
+ audit Record and label agent interactions (append-only JSONL)
+ blocked Show blocked issues
+ completion Generate the autocompletion script for the specified shell
+ cook Compile a formula into a proto (ephemeral by default)
+ defer Defer one or more issues for later
+ formula Manage workflow formulas
+ gitlab GitLab integration commands
+ help Help about any command
+ hook Execute a git hook (called by hook scripts)
+ mail Delegate to mail provider (e.g., gt mail)
+ mol Molecule commands (work templates)
+ orphans Identify orphaned issues (referenced in commits but still open)
+ ready Show ready work (open, no blockers)
+ rename Rename an issue ID
+ ship Publish a capability for cross-project dependencies
+ slot Manage agent bead slots
+ undefer Undefer one or more issues (restore to open)
+ version Print version information
+
+Flags:
+ --actor string Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
+ --allow-stale Allow operations on potentially stale data (skip staleness check)
+ --db string Database path (default: auto-discover .beads/*.db)
+ --dolt-auto-commit string Dolt backend: auto-commit after write commands (off|on). Default from config key dolt.auto-commit
+ -h, --help help for bd
+ --json Output in JSON format
+ --lock-timeout duration SQLite busy timeout (0 = fail immediately if locked) (default 30s)
+ --no-auto-flush Disable automatic JSONL sync after CRUD operations
+ --no-auto-import Disable automatic JSONL import when newer than DB
+ --no-daemon Force direct storage mode, bypass daemon if running
+ --no-db Use no-db mode: load from JSONL, no SQLite
+ --profile Generate CPU profile for performance analysis
+ -q, --quiet Suppress non-essential output (errors only)
+ --readonly Read-only mode: block write operations (for worker sandboxes)
+ --sandbox Sandbox mode: disables daemon and auto-sync
+ -v, --verbose Enable verbose/debug output
+ -V, --version Print version information
+
+Use "bd [command] --help" for more information about a command.
diff --git a/label-help.txt b/help/cli/label-help.txt
similarity index 100%
rename from label-help.txt
rename to help/cli/label-help.txt
diff --git a/state-help.txt b/help/cli/state-help.txt
similarity index 100%
rename from state-help.txt
rename to help/cli/state-help.txt
diff --git a/true_agents.txt b/help/cli/true_agents.txt
similarity index 100%
rename from true_agents.txt
rename to help/cli/true_agents.txt
diff --git a/help/workflows/agent_bead_workflow.txt b/help/workflows/agent_bead_workflow.txt
new file mode 100644
index 0000000..ce3349b
--- /dev/null
+++ b/help/workflows/agent_bead_workflow.txt
@@ -0,0 +1,53 @@
+# Agent Workflow for Beadboard
+
+As an agent working in this repository, you must follow these rules when managing tasks using `bd`.
+
+---
+
+## 1. Finding Work
+Before starting any new work, check if there's already an open task for it.
+```bash
+bd ready
+```
+*If a task is ready, pick it up instead of creating a duplicate.*
+
+## 2. Starting Work / Tracking Plans
+When asked to perform non-trivial work without an existing task, **always create a task**.
+Do **not** keep your plan in free-form text. Create a task with `priority 0`.
+```bash
+bd create "Short descriptive title of the work" -p 0
+```
+Update the status to `in_progress` if you are working on it:
+```bash
+bd set-state in_progress
+```
+
+## 3. Working within Tasks (task.md)
+Update the local `/brain//task.md` using the checklist `[ ]`, `[/]`, `[x]` to maintain your internal progress while working. Also update the `bd` task if you have significant architectural notes.
+
+## 4. Dependencies
+If your task depends on another task being completed first, declare the block:
+```bash
+# Link: your task is blocked by another task
+# First run bd dep add, it will prompt you interactively.
+# Or use the appropriate arguments if you know them.
+# The user prefers bd handle these rather than prose "do X after Y"
+```
+
+## 5. Finishing Work
+When you have finished a task, completed your tests, and verified it works (run your lint/typecheck steps), you must close the task.
+
+1. **Verify completion**: `bun run typecheck && bun run lint`
+2. **Close the bead**:
+ ```bash
+ # You can use bd update or bd close
+ bd status # To view it
+ bd close # To mark it closed
+ ```
+3. **Summarize**: Leave a summary of what changed. (You can do this by using bd edit or through a comment if bd supports it, otherwise summarize in your git commit).
+
+## 6. Verifying Past Work (Recently Closed Beads)
+If you need to know what was just finished (e.g. to see if a bead was successfully closed), view the recently closed beads:
+```bash
+bd query "status=closed" --sort closed --reverse --limit 5
+```
diff --git a/help/workflows/dolt_backend_workflow.txt b/help/workflows/dolt_backend_workflow.txt
new file mode 100644
index 0000000..c998992
--- /dev/null
+++ b/help/workflows/dolt_backend_workflow.txt
@@ -0,0 +1,52 @@
+# Beadboard Dolt System Workflow
+
+Beadboard supports an optional **Dolt storage backend**. Dolt is a SQL database with git-like version control, enabling advanced features like branching, merging, and historic diffs for your issue data.
+
+If your environment has Dolt enabled (no CGO build errors when using `bd`), you have access to powerful new version control commands. They behave similarly to `git` but operate purely on Beadboard issues.
+
+## 1. Branching
+You can create branches of your issue database, to test speculative features or isolate a swarm of issues before merging them into main.
+
+- **List all branches**:
+ ```bash
+ bd branch
+ ```
+- **Create a new branch**:
+ ```bash
+ bd branch
+ ```
+
+## 2. Version Control (Commit & Merge)
+Use `bd vc` to manage commits on your branch.
+
+- **View status of current branch**:
+ ```bash
+ bd vc status
+ ```
+- **Create a commit**:
+ ```bash
+ bd vc commit
+ ```
+- **Merge a branch**:
+ ```bash
+ bd vc merge
+ ```
+
+*Note: You can also rely on `--dolt-auto-commit=on` (which can be set in config) to automatically commit changes after write operations like `bd create` or `bd update`.*
+
+## 3. Viewing Diffs
+You can view the exact issue changes (created, deleted, modified) between two commits or branches.
+
+- **Compare current state against a branch**:
+ ```bash
+ bd diff main feature-branch
+ ```
+- **Compare history**:
+ ```bash
+ bd diff HEAD~5 HEAD # Show changes in the last 5 commits
+ ```
+
+## Summary for Agents
+If you receive an error about `dolt backend requires CGO` when running `bd ready`, it means the Dolt features are not available on this specific build. You must fall back to standard `bd` commands which use SQLite by default and sync via JSONL files.
+
+However, when working in a Dolt-enabled environment, you should proactively create a branch when starting a large Epic (`bd branch feature-xyz`), commit your `bd` issue changes natively tracking the state (`bd vc commit`), and merge them back when the epic is verified (`bd vc merge`).
diff --git a/help/workflows/viewing_recent_closed_beads.txt b/help/workflows/viewing_recent_closed_beads.txt
new file mode 100644
index 0000000..374d607
--- /dev/null
+++ b/help/workflows/viewing_recent_closed_beads.txt
@@ -0,0 +1,49 @@
+# Viewing Recently Closed Beads
+
+When you need to find beads (tasks, issues) that were recently closed, use `bd query` or `bd list` with date filters.
+The user rule indicates a need to "correctly view the last closed beads (there is some sort of filter for recency)".
+
+## Method 1: Using `bd query`
+
+`bd query` supports a simple query language with relative and absolute dates.
+
+1. **View closed beads in the last X days**
+ ```bash
+ bd query "status=closed AND updated>2d" --sort updated
+ ```
+ *This finds beads closed and updated within the last 2 days, sorted chronologically with newest at the bottom.*
+
+2. **View closed beads in the last 24 hours**
+ ```bash
+ bd query "status=closed AND updated>24h" --sort updated
+ ```
+
+3. **View everything closed**
+ ```bash
+ bd query "status=closed" --sort closed --limit 10 --reverse
+ ```
+ *This shows the 10 most recently closed beads (requires --reverse so limit grabs the newest).*
+
+## Method 2: Using `bd list`
+
+`bd list` has specific flags for filtering by closure date.
+
+1. **View closed beads using --closed-after**
+ ```bash
+ bd list --status closed --closed-after "7d" --sort closed --reverse
+ ```
+ Wait, the `--closed-after` flag expects YYYY-MM-DD or RFC3339. The better approach for relative dates is `bd query`.
+
+However, if using absolute dates:
+```bash
+bd list --status closed --closed-after 2025-01-01 --sort closed --reverse
+```
+
+## Summary for Agents:
+**Always use `bd query` with relative time for the best results** when checking recency.
+
+To view recently closed beads (within the last 3 days) in standard terminal chronological order (oldest at top, newest at bottom):
+**`bd query "status=closed AND closed>3d" --sort closed`**
+
+To get just the last 5 closed beads (note: you must use --reverse to get the most recent ones when using --limit):
+**`bd query "status=closed" --sort closed --reverse --limit 5`**
diff --git a/image-2.png b/image-2.png
new file mode 100644
index 0000000..fb7051e
Binary files /dev/null and b/image-2.png differ
diff --git a/image-3.png b/image-3.png
new file mode 100644
index 0000000..2837671
Binary files /dev/null and b/image-3.png differ
diff --git a/image-4.png b/image-4.png
new file mode 100644
index 0000000..f3d274c
Binary files /dev/null and b/image-4.png differ
diff --git a/image-5.png b/image-5.png
new file mode 100644
index 0000000..2837671
Binary files /dev/null and b/image-5.png differ
diff --git a/image-6.png b/image-6.png
new file mode 100644
index 0000000..fa486a5
Binary files /dev/null and b/image-6.png differ
diff --git a/image-7.png b/image-7.png
new file mode 100644
index 0000000..5d0d82a
Binary files /dev/null and b/image-7.png differ
diff --git a/image-8.png b/image-8.png
new file mode 100644
index 0000000..fa486a5
Binary files /dev/null and b/image-8.png differ
diff --git a/image-9.png b/image-9.png
new file mode 100644
index 0000000..6a92dbb
Binary files /dev/null and b/image-9.png differ
diff --git a/next.config.ts b/next.config.ts
index 0076578..05d1bdb 100644
--- a/next.config.ts
+++ b/next.config.ts
@@ -4,6 +4,30 @@ import path from 'node:path';
const nextConfig: NextConfig = {
reactStrictMode: true,
outputFileTracingRoot: path.join(process.cwd()),
+ async redirects() {
+ return [
+ {
+ source: '/graph',
+ destination: '/?view=graph',
+ permanent: false,
+ },
+ {
+ source: '/sessions',
+ destination: '/?view=social',
+ permanent: false,
+ },
+ {
+ source: '/timeline',
+ destination: '/?view=activity',
+ permanent: false,
+ },
+ {
+ source: '/mockup',
+ destination: '/',
+ permanent: false,
+ },
+ ];
+ },
webpack(config, { dev }) {
if (dev) {
// Avoid intermittent Windows ENOENT errors from webpack filesystem pack cache.
diff --git a/reference/routes/README.md b/reference/routes/README.md
new file mode 100644
index 0000000..7e11720
--- /dev/null
+++ b/reference/routes/README.md
@@ -0,0 +1,24 @@
+# Reference Routes Vault
+
+This folder stores archived route implementations that are not part of the active runtime surface.
+
+## Purpose
+- Preserve prior functionality and UI patterns for reuse.
+- Keep the active `src/app` route tree lean and maintainable.
+- Prevent archived routes from affecting lint/typecheck/test gates.
+
+## Current archived routes
+- `app/graph/page.tsx` (legacy dedicated graph route)
+- `app/sessions/page.tsx` (legacy sessions redirect route)
+- `app/timeline/page.tsx` (legacy timeline route)
+- `app/mockup/page.tsx` (legacy mockup playground)
+- `app/page-old.tsx` (legacy main page composition)
+
+## Restore workflow
+1. Copy the archived file(s) back into `src/app/...`.
+2. Reconnect links/navigation.
+3. Re-run `npm run typecheck`, `npm run lint`, `npm run test`.
+
+## Notes
+- Runtime now uses query-driven views from `/` (`view=social|graph|activity`).
+- Backward URL compatibility is handled through redirects in `next.config.ts`.
diff --git a/src/app/graph/page.tsx b/reference/routes/app/graph/page.tsx
similarity index 100%
rename from src/app/graph/page.tsx
rename to reference/routes/app/graph/page.tsx
diff --git a/src/app/mockup/page.tsx b/reference/routes/app/mockup/page.tsx
similarity index 100%
rename from src/app/mockup/page.tsx
rename to reference/routes/app/mockup/page.tsx
diff --git a/src/app/page-old.tsx b/reference/routes/app/page-old.tsx
similarity index 100%
rename from src/app/page-old.tsx
rename to reference/routes/app/page-old.tsx
diff --git a/src/app/sessions/page.tsx b/reference/routes/app/sessions/page.tsx
similarity index 100%
rename from src/app/sessions/page.tsx
rename to reference/routes/app/sessions/page.tsx
diff --git a/src/app/timeline/page.tsx b/reference/routes/app/timeline/page.tsx
similarity index 100%
rename from src/app/timeline/page.tsx
rename to reference/routes/app/timeline/page.tsx
diff --git a/src/app/api/bd/health/route.ts b/src/app/api/bd/health/route.ts
new file mode 100644
index 0000000..ff17e4c
--- /dev/null
+++ b/src/app/api/bd/health/route.ts
@@ -0,0 +1,37 @@
+import { NextResponse } from 'next/server';
+
+import { runBdCommand } from '../../../../lib/bridge';
+
+export const dynamic = 'force-dynamic';
+
+export async function GET(request: Request): Promise {
+ const { searchParams } = new URL(request.url);
+ const projectRoot = searchParams.get('projectRoot') ?? process.cwd();
+
+ const result = await runBdCommand({
+ projectRoot,
+ args: ['--version'],
+ timeoutMs: 8_000,
+ });
+
+ if (!result.success) {
+ const status = result.classification === 'not_found' ? 503 : 500;
+ return NextResponse.json(
+ {
+ ok: false,
+ error: {
+ classification: result.classification ?? 'unknown',
+ message: result.error ?? result.stderr ?? 'bd health check failed',
+ },
+ },
+ { status },
+ );
+ }
+
+ return NextResponse.json({
+ ok: true,
+ data: {
+ version: result.stdout,
+ },
+ });
+}
diff --git a/src/app/api/beads/_shared.ts b/src/app/api/beads/_shared.ts
index e5f5c50..b1399fa 100644
--- a/src/app/api/beads/_shared.ts
+++ b/src/app/api/beads/_shared.ts
@@ -29,7 +29,7 @@ export async function handleMutationRequest(request: Request, operation: Mutatio
const payload = validateMutationPayload(operation, body);
const result = await executeMutation(operation, payload);
- const status = result.ok ? 200 : result.error?.classification === 'not_found' ? 404 : 400;
+ const status = result.ok ? 200 : result.error?.classification === 'not_found' ? 503 : 400;
return NextResponse.json(result, { status });
} catch (error) {
if (error instanceof MutationValidationError) {
diff --git a/src/app/api/coord/events/route.ts b/src/app/api/coord/events/route.ts
new file mode 100644
index 0000000..6a3e50c
--- /dev/null
+++ b/src/app/api/coord/events/route.ts
@@ -0,0 +1,56 @@
+import { NextResponse } from 'next/server';
+
+import { writeCoordEvent } from '../../../../lib/coord-events';
+
+interface CoordEventsDeps {
+ writeCoordEvent: typeof writeCoordEvent;
+}
+
+function parseBody(data: unknown): { projectRoot: string; event: unknown } | null {
+ if (!data || typeof data !== 'object') return null;
+ const record = data as Record;
+ if (typeof record.projectRoot !== 'string' || !record.projectRoot.trim()) return null;
+ return {
+ projectRoot: record.projectRoot.trim(),
+ event: record.event,
+ };
+}
+
+export async function handleCoordEventsPost(
+ request: Request,
+ deps?: Partial,
+): Promise {
+ let body: unknown;
+ try {
+ body = await request.json();
+ } catch {
+ return NextResponse.json(
+ { ok: false, error: { classification: 'bad_args', message: 'Invalid JSON body' } },
+ { status: 400 },
+ );
+ }
+
+ const parsed = parseBody(body);
+ if (!parsed) {
+ return NextResponse.json(
+ { ok: false, error: { classification: 'bad_args', message: 'projectRoot and event are required' } },
+ { status: 400 },
+ );
+ }
+
+ const writer = deps?.writeCoordEvent ?? writeCoordEvent;
+ const result = await writer(parsed.event, { projectRoot: parsed.projectRoot });
+ if (!result.ok) {
+ const status = result.error.classification === 'bad_args' ? 400 : 500;
+ return NextResponse.json(
+ { ok: false, error: { classification: result.error.classification, message: result.error.message } },
+ { status },
+ );
+ }
+
+ return NextResponse.json({ ok: true, eventId: result.eventId });
+}
+
+export async function POST(request: Request): Promise {
+ return handleCoordEventsPost(request);
+}
diff --git a/src/app/api/sessions/[beadId]/conversation/route.ts b/src/app/api/sessions/[beadId]/conversation/route.ts
index bac7b34..6548b47 100644
--- a/src/app/api/sessions/[beadId]/conversation/route.ts
+++ b/src/app/api/sessions/[beadId]/conversation/route.ts
@@ -22,7 +22,7 @@ export async function GET(
const activity = history.filter((e: ActivityEvent) => e.beadId === beadId);
// 2. Get communication for this bead
- const summary = await getCommunicationSummary();
+ const summary = await getCommunicationSummary(projectRoot);
const messages = summary.messages.filter((m: AgentMessage) => m.bead_id === beadId);
// 3. Get local bd interactions via CLI
@@ -55,4 +55,4 @@ export async function GET(
console.error('[API/Sessions/Conversation] Failed:', error);
return NextResponse.json({ ok: false, error: String(error) }, { status: 500 });
}
-}
\ No newline at end of file
+}
diff --git a/src/app/api/sessions/route.ts b/src/app/api/sessions/route.ts
index e9a3395..b018d92 100644
--- a/src/app/api/sessions/route.ts
+++ b/src/app/api/sessions/route.ts
@@ -41,9 +41,9 @@ export async function GET(request: Request): Promise {
try {
const issues = await readIssuesFromDisk({ projectRoot, preferBd: true });
const activity = activityEventBus.getHistory(projectRoot);
- const communication = await getCommunicationSummary();
+ const communication = await getCommunicationSummary(projectRoot);
const livenessMap = await getAgentLivenessMap(projectRoot, activity);
- const incursions = await calculateIncursions();
+ const incursions = await calculateIncursions(projectRoot, livenessMap);
const agentsResult = await listAgents({}, { projectRoot });
const feed = buildSessionTaskFeed(issues, activity, communication, livenessMap);
diff --git a/src/app/api/swarm/list/route.ts b/src/app/api/swarm/list/route.ts
index 37aec33..a26ab08 100644
--- a/src/app/api/swarm/list/route.ts
+++ b/src/app/api/swarm/list/route.ts
@@ -21,9 +21,10 @@ export async function GET(request: Request): Promise {
});
if (!result.success) {
+ const status = result.classification === 'not_found' ? 503 : 400;
return NextResponse.json(
{ ok: false, error: { classification: result.classification ?? 'unknown', message: result.error ?? result.stderr } },
- { status: 400 },
+ { status },
);
}
diff --git a/src/app/api/swarm/status/route.ts b/src/app/api/swarm/status/route.ts
index 4d7e3b8..6e9a138 100644
--- a/src/app/api/swarm/status/route.ts
+++ b/src/app/api/swarm/status/route.ts
@@ -29,9 +29,10 @@ export async function GET(request: Request): Promise {
});
if (!result.success) {
+ const status = result.classification === 'not_found' ? 503 : 400;
return NextResponse.json(
{ ok: false, error: { classification: result.classification ?? 'unknown', message: result.error ?? result.stderr } },
- { status: 400 },
+ { status },
);
}
diff --git a/src/app/globals.css b/src/app/globals.css
index a84e8b4..c4d448f 100644
--- a/src/app/globals.css
+++ b/src/app/globals.css
@@ -6,27 +6,27 @@
:root {
/* ========== VISUAL-TRUTH UI TOKEN CONTRACT (bb-vt.1.1) ========== */
- /* Warm charcoal aurora palette - DISTINCT LAYERS */
- --ui-bg-app: #181716; /* Darkest - page background */
- --ui-bg-header: #131211; /* Header - darker than sidebar */
- --ui-bg-shell: #1f1e1d; /* Sidebar - distinct from main */
- --ui-bg-panel: #282725; /* Panels/cards within sidebar */
- --ui-bg-main: #242322; /* Main content area - distinct */
- --ui-bg-card: #302e2c; /* Cards - lightest layer */
- --ui-bg-elevated: #3a3836; /* Elevated/selected elements */
+ /* Map legacy --ui-* tokens to theme tokens so all themes work consistently */
+ --ui-bg-app: var(--surface-backdrop);
+ --ui-bg-header: var(--surface-primary);
+ --ui-bg-shell: var(--surface-primary);
+ --ui-bg-panel: var(--surface-secondary);
+ --ui-bg-main: var(--surface-secondary);
+ --ui-bg-card: var(--surface-elevated);
+ --ui-bg-elevated: var(--surface-elevated);
- --ui-border-soft: rgba(180, 175, 165, 0.2);
- --ui-border-strong: rgba(180, 175, 165, 0.35);
+ --ui-border-soft: var(--border-subtle);
+ --ui-border-strong: var(--border-default);
- --ui-text-primary: #f0eeea;
- --ui-text-muted: #a8a49a;
+ --ui-text-primary: var(--text-primary);
+ --ui-text-muted: var(--text-tertiary);
- --ui-accent-ready: #35d98f;
- --ui-accent-blocked: #ff4c72;
- --ui-accent-warning: #ffb24a;
- --ui-accent-info: #35c9ff;
- --ui-accent-action-green: #35d98f;
- --ui-accent-action-red: #ff4c72;
+ --ui-accent-ready: var(--accent-success);
+ --ui-accent-blocked: var(--accent-danger);
+ --ui-accent-warning: var(--accent-warning);
+ --ui-accent-info: var(--accent-info);
+ --ui-accent-action-green: var(--accent-success);
+ --ui-accent-action-red: var(--accent-danger);
--ui-font-sans: 'Inter', 'Segoe UI', system-ui, -apple-system, sans-serif;
--ui-font-mono: 'JetBrains Mono', 'Cascadia Code', 'Fira Code', monospace;
@@ -43,30 +43,25 @@
--color-accent-teal: var(--ui-accent-info);
--color-text-primary: var(--ui-text-primary);
- --color-text-secondary: #c4cfdb;
+ --color-text-secondary: var(--text-secondary);
--color-text-muted: var(--ui-text-muted);
- --color-text-on-primary: #10161d;
+ --color-text-on-primary: var(--text-inverse);
--color-border-default: var(--ui-border-strong);
--color-border-subtle: var(--ui-border-soft);
/* Status colors */
- --status-open: var(--ui-accent-info);
- --status-ready: var(--ui-accent-ready);
- --status-in-progress: var(--ui-accent-warning);
- --status-progress: var(--ui-accent-warning);
- --status-blocked: var(--ui-accent-blocked);
- --status-blocked-earthy: var(--ui-accent-blocked);
- --status-closed: #7f8b98;
- --status-closed-earthy: #7f8b98;
- --status-deferred: #7f8b98;
+ --status-open: var(--accent-info);
+ --status-progress: var(--status-in-progress);
+ --status-blocked-earthy: var(--status-blocked);
+ --status-closed-earthy: var(--status-closed);
/* Liveness colors */
--liveness-active: var(--ui-accent-ready);
--liveness-stale: var(--ui-accent-warning);
--liveness-stuck: var(--ui-accent-action-red);
--liveness-dead: var(--ui-accent-action-red);
- --liveness-idle: #7f8b98;
+ --liveness-idle: var(--text-tertiary);
/* Agent Role Colors */
--agent-role-ui: #6B9BD2;
@@ -83,10 +78,10 @@
--priority-p4: #64748b;
/* Blocks/Unlocks Section Colors */
- --color-blocks-bg: rgba(212, 165, 116, 0.1);
- --color-unlocks-bg: rgba(229, 115, 115, 0.1);
- --color-blocks-border: rgba(212, 165, 116, 0.2);
- --color-unlocks-border: rgba(229, 115, 115, 0.2);
+ --color-blocks-bg: var(--status-in-progress);
+ --color-unlocks-bg: var(--status-blocked);
+ --color-blocks-border: color-mix(in srgb, var(--accent-warning) 35%, transparent);
+ --color-unlocks-border: color-mix(in srgb, var(--accent-danger) 35%, transparent);
/* ========== RADI ========== */
--radius-sm: 0.375rem;
@@ -98,10 +93,8 @@
--radius-pill: 9999px;
/* ========== SHADOWS ========== */
- --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.1);
- --shadow-md: 0 4px 12px rgba(0, 0, 0, 0.15);
- --shadow-soft-lg: 0 10px 30px -10px rgba(0, 0, 0, 0.3);
- --shadow-soft-xl: 0 20px 40px -10px rgba(0, 0, 0, 0.4);
+ --shadow-soft-lg: var(--shadow-md);
+ --shadow-soft-xl: var(--shadow-lg);
/* ========== TYPOGRAPHY ========== */
--font-ui-stack: var(--ui-font-sans);
@@ -139,13 +132,12 @@
--sidebar-right-width: 17.5rem;
--topbar-height: 3.75rem;
- --glass-base: linear-gradient(180deg,
- color-mix(in srgb, var(--ui-bg-card) 72%, black),
- color-mix(in srgb, var(--ui-bg-panel) 78%, black));
- --edge-top: color-mix(in srgb, var(--ui-border-strong) 80%, white 20%);
- --edge-bottom: color-mix(in srgb, var(--ui-border-soft) 75%, black 25%);
- --elevation-ambient: 0 20px 40px -16px rgba(0, 0, 0, 0.78);
- --elevation-tight: 0 10px 24px -12px rgba(0, 0, 0, 0.7);
+ --glass-base: linear-gradient(180deg, var(--surface-elevated), var(--surface-secondary));
+ --edge-side: var(--ui-border-soft);
+ --edge-top: color-mix(in srgb, var(--ui-border-strong) 88%, white 12%);
+ --edge-bottom: color-mix(in srgb, var(--ui-border-soft) 88%, black 12%);
+ --elevation-ambient: var(--shadow-lg);
+ --elevation-tight: var(--shadow-md);
/* ========== LEGACY COMPATIBILITY TOKENS ========== */
/* For existing components that reference these */
@@ -181,7 +173,7 @@ body {
* {
scrollbar-width: thin;
- scrollbar-color: rgba(148, 163, 184, 0.35) rgba(255, 255, 255, 0.02);
+ scrollbar-color: var(--scrollbar-thumb) var(--scrollbar-track);
}
*::-webkit-scrollbar {
@@ -190,18 +182,18 @@ body {
}
*::-webkit-scrollbar-track {
- background: rgba(255, 255, 255, 0.02);
+ background: var(--scrollbar-track);
border-radius: 9999px;
}
*::-webkit-scrollbar-thumb {
- background: linear-gradient(180deg, rgba(156, 163, 175, 0.55), rgba(107, 114, 128, 0.45));
- border: 1px solid rgba(255, 255, 255, 0.1);
+ background: var(--scrollbar-thumb);
+ border: 1px solid color-mix(in srgb, var(--scrollbar-thumb) 70%, transparent);
border-radius: 9999px;
}
*::-webkit-scrollbar-thumb:hover {
- background: linear-gradient(180deg, rgba(186, 194, 209, 0.72), rgba(124, 136, 156, 0.62));
+ background: var(--scrollbar-thumb-hover);
}
.custom-scrollbar::-webkit-scrollbar {
@@ -210,12 +202,12 @@ body {
}
.custom-scrollbar::-webkit-scrollbar-thumb {
- background: rgba(148, 163, 184, 0.15);
+ background: var(--scrollbar-thumb);
border-radius: 20px;
}
.custom-scrollbar::-webkit-scrollbar-thumb:hover {
- background: rgba(148, 163, 184, 0.3);
+ background: var(--scrollbar-thumb-hover);
}
.no-scrollbar::-webkit-scrollbar {
@@ -229,14 +221,14 @@ body {
.workflow-card {
- border: 1px solid rgba(255, 255, 255, 0.08);
- border-top-color: rgba(255, 255, 255, 0.24);
- border-bottom-color: rgba(0, 0, 0, 0.9);
- background: linear-gradient(180deg, rgba(42, 44, 52, 0.6) 0%, rgba(22, 23, 28, 0.6) 100%);
+ border: 1px solid var(--border-default);
+ border-top-color: color-mix(in srgb, var(--border-strong) 88%, white 12%);
+ border-bottom-color: color-mix(in srgb, var(--border-subtle) 88%, black 12%);
+ background: linear-gradient(180deg, var(--surface-quaternary) 0%, var(--surface-secondary) 100%);
box-shadow:
var(--elevation-ambient),
var(--elevation-tight),
- inset 0 1px 1px rgba(255, 255, 255, 0.15);
+ inset 0 1px 1px color-mix(in srgb, var(--alpha-white-high) 40%, transparent);
backdrop-filter: blur(24px) saturate(120%);
-webkit-backdrop-filter: blur(24px) saturate(120%);
transform: translateZ(0);
@@ -244,14 +236,14 @@ body {
}
.workflow-card-selected {
- border-color: rgba(96, 165, 250, 0.42);
- border-top-color: rgba(96, 165, 250, 0.58);
- background: linear-gradient(180deg, rgba(60, 68, 88, 0.7) 0%, rgba(35, 40, 52, 0.7) 100%);
+ border-color: color-mix(in srgb, var(--accent-info) 42%, var(--border-default));
+ border-top-color: color-mix(in srgb, var(--accent-info) 58%, var(--border-strong));
+ background: linear-gradient(180deg, color-mix(in srgb, var(--surface-active) 55%, var(--surface-elevated)), var(--surface-secondary));
box-shadow:
- 0 20px 48px -8px rgba(0, 0, 0, 0.9),
- 0 0 0 1px rgba(96, 165, 250, 0.25),
- 0 0 40px rgba(96, 165, 250, 0.15),
- inset 0 1px 1px rgba(255, 255, 255, 0.3);
+ var(--shadow-lg),
+ 0 0 0 1px color-mix(in srgb, var(--accent-info) 25%, transparent),
+ var(--glow-info),
+ inset 0 1px 1px color-mix(in srgb, var(--alpha-white-high) 50%, transparent);
}
.glass-panel {
@@ -265,19 +257,19 @@ body {
}
.bg-earthy-gradient {
- background: linear-gradient(to bottom right, #2D2D2D, #363636);
+ background: linear-gradient(to bottom right, var(--surface-secondary), var(--surface-tertiary));
}
-/* Shared dark form controls to avoid white-on-white browser defaults */
+/* Shared themed form controls */
.ui-field {
- border: 1px solid rgba(255, 255, 255, 0.1);
+ border: 1px solid var(--border-default);
border-top-color: var(--edge-top);
border-bottom-color: var(--edge-bottom);
- background: linear-gradient(180deg, rgba(32, 34, 42, 0.72), rgba(17, 19, 26, 0.72));
+ background: linear-gradient(180deg, var(--surface-input), var(--surface-secondary));
color: var(--color-text-strong);
box-shadow:
- 0 8px 20px -12px rgba(0, 0, 0, 0.85),
- inset 0 1px 0 rgba(255, 255, 255, 0.06);
+ var(--shadow-sm),
+ inset 0 1px 0 color-mix(in srgb, var(--alpha-white-high) 22%, transparent);
backdrop-filter: blur(12px);
-webkit-backdrop-filter: blur(12px);
}
@@ -288,10 +280,10 @@ body {
.ui-field:focus-visible {
outline: none;
- border-color: rgba(96, 165, 250, 0.48);
+ border-color: color-mix(in srgb, var(--accent-info) 48%, var(--border-default));
box-shadow:
- 0 0 0 2px rgba(96, 165, 250, 0.2),
- inset 0 1px 0 rgba(255, 255, 255, 0.06);
+ 0 0 0 2px color-mix(in srgb, var(--accent-info) 20%, transparent),
+ inset 0 1px 0 color-mix(in srgb, var(--alpha-white-high) 22%, transparent);
}
.ui-select {
@@ -326,19 +318,19 @@ body {
}
.ui-shell-topbar {
- background: linear-gradient(180deg, color-mix(in srgb, var(--ui-bg-panel) 92%, black), var(--ui-bg-shell));
+ background: linear-gradient(180deg, var(--ui-bg-panel), var(--ui-bg-shell));
border-bottom: 1px solid color-mix(in srgb, var(--ui-accent-info) 22%, var(--ui-border-soft));
- box-shadow: 0 10px 24px -20px rgba(0, 0, 0, 0.9);
+ box-shadow: var(--shadow-sm);
}
.ui-shell-middle {
- background: linear-gradient(180deg, color-mix(in srgb, var(--ui-bg-app) 74%, black), color-mix(in srgb, var(--ui-bg-app) 90%, black));
+ background: linear-gradient(180deg, var(--ui-bg-app), var(--ui-bg-main));
border-left: 1px solid color-mix(in srgb, var(--ui-accent-info) 20%, var(--ui-border-soft));
border-right: 1px solid color-mix(in srgb, var(--ui-accent-info) 20%, var(--ui-border-soft));
}
.ui-shell-panel {
- background: linear-gradient(180deg, color-mix(in srgb, var(--ui-bg-shell) 86%, black), color-mix(in srgb, var(--ui-bg-panel) 84%, black));
+ background: linear-gradient(180deg, var(--ui-bg-shell), var(--ui-bg-panel));
border-left: 1px solid color-mix(in srgb, var(--ui-accent-info) 30%, var(--ui-border-soft));
}
@@ -349,8 +341,8 @@ body {
.workflow-graph-legend {
backdrop-filter: blur(12px);
- background: rgba(20, 23, 31, 0.72);
- box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.05), 0 8px 32px rgba(0, 0, 0, 0.3);
+ background: color-mix(in srgb, var(--surface-overlay) 78%, transparent);
+ box-shadow: inset 0 1px 0 color-mix(in srgb, var(--alpha-white-high) 22%, transparent), var(--shadow-md);
}
.workflow-graph-flow .react-flow__viewport {
diff --git a/src/components/activity/activity-panel.tsx b/src/components/activity/activity-panel.tsx
index 8df8023..89744b9 100644
--- a/src/components/activity/activity-panel.tsx
+++ b/src/components/activity/activity-panel.tsx
@@ -111,25 +111,25 @@ export function formatRelativeTime(timestamp: string): string {
function getAgentTone(status: AgentStatus): AgentTone {
const tones: Record = {
active: {
- cardClass: 'bg-[#173126]',
+ cardClass: 'bg-[var(--status-ready)]',
labelClass: 'text-[#7CB97A]',
ringClass: 'ring-[#7CB97A]/45',
glowClass: 'bg-[#7CB97A]/30',
},
stale: {
- cardClass: 'bg-[#322817]',
+ cardClass: 'bg-[var(--status-in-progress)]',
labelClass: 'text-[#D4A574]',
ringClass: 'ring-[#D4A574]/45',
glowClass: 'bg-[#D4A574]/30',
},
stuck: {
- cardClass: 'bg-[#341a1f]',
+ cardClass: 'bg-[var(--status-blocked)]',
labelClass: 'text-[#C97A7A]',
ringClass: 'ring-[#C97A7A]/45',
glowClass: 'bg-[#C97A7A]/30',
},
dead: {
- cardClass: 'bg-[#2b232b]',
+ cardClass: 'bg-[var(--surface-primary)]',
labelClass: 'text-[#A78A94]',
ringClass: 'ring-[#A78A94]/40',
glowClass: 'bg-[#A78A94]/25',
@@ -147,84 +147,84 @@ export function getEventTone(kind: string): EventTone {
label: 'Created',
labelClass: 'text-[#7CB97A]',
dotClass: 'bg-[#7CB97A]',
- cardClass: 'bg-[#182f25]',
+ cardClass: 'bg-[var(--status-ready)]',
idClass: 'text-[#9ACB98]',
},
opened: {
label: 'Opened',
labelClass: 'text-[#7CB97A]',
dotClass: 'bg-[#7CB97A]',
- cardClass: 'bg-[#182f25]',
+ cardClass: 'bg-[var(--status-ready)]',
idClass: 'text-[#9ACB98]',
},
closed: {
label: 'Closed',
labelClass: 'text-[#D4A574]',
dotClass: 'bg-[#D4A574]',
- cardClass: 'bg-[#332716]',
+ cardClass: 'bg-[var(--status-in-progress)]',
idClass: 'text-[#DAB891]',
},
reopened: {
label: 'Reopened',
labelClass: 'text-[#5B95E8]',
dotClass: 'bg-[#5B95E8]',
- cardClass: 'bg-[#1b2b43]',
+ cardClass: 'bg-[var(--surface-primary)]',
idClass: 'text-[#8DB4EF]',
},
status_changed: {
label: 'Status changed',
labelClass: 'text-[#D4A574]',
dotClass: 'bg-[#D4A574]',
- cardClass: 'bg-[#2f2518]',
+ cardClass: 'bg-[var(--status-in-progress)]',
idClass: 'text-[#DAB891]',
},
priority_changed: {
label: 'Priority changed',
labelClass: 'text-[#D4A574]',
dotClass: 'bg-[#D4A574]',
- cardClass: 'bg-[#2f2518]',
+ cardClass: 'bg-[var(--status-in-progress)]',
idClass: 'text-[#DAB891]',
},
assignee_changed: {
label: 'Assigned',
labelClass: 'text-[#D4A574]',
dotClass: 'bg-[#D4A574]',
- cardClass: 'bg-[#2f2518]',
+ cardClass: 'bg-[var(--status-in-progress)]',
idClass: 'text-[#DAB891]',
},
dependency_added: {
label: 'Dependency added',
labelClass: 'text-[#D4A574]',
dotClass: 'bg-[#D4A574]',
- cardClass: 'bg-[#2f2518]',
+ cardClass: 'bg-[var(--status-in-progress)]',
idClass: 'text-[#DAB891]',
},
dependency_removed: {
label: 'Dependency removed',
labelClass: 'text-[#C97A7A]',
dotClass: 'bg-[#C97A7A]',
- cardClass: 'bg-[#321b21]',
+ cardClass: 'bg-[var(--status-blocked)]',
idClass: 'text-[#D9A9A9]',
},
heartbeat: {
label: 'Heartbeat',
labelClass: 'text-[#5BA8A0]',
dotClass: 'bg-[#5BA8A0]',
- cardClass: 'bg-[#173034]',
+ cardClass: 'bg-[var(--surface-primary)]',
idClass: 'text-[#8BC9C1]',
},
commented: {
label: 'Commented',
labelClass: 'text-[#5BA8A0]',
dotClass: 'bg-[#5BA8A0]',
- cardClass: 'bg-[#173034]',
+ cardClass: 'bg-[var(--surface-primary)]',
idClass: 'text-[#8BC9C1]',
},
comment_added: {
label: 'Commented',
labelClass: 'text-[#5BA8A0]',
dotClass: 'bg-[#5BA8A0]',
- cardClass: 'bg-[#173034]',
+ cardClass: 'bg-[var(--surface-primary)]',
idClass: 'text-[#8BC9C1]',
},
};
@@ -234,7 +234,7 @@ export function getEventTone(kind: string): EventTone {
label: normalized.replace(/_/g, ' '),
labelClass: 'text-[#5BA8A0]',
dotClass: 'bg-[#5BA8A0]',
- cardClass: 'bg-[#173034]',
+ cardClass: 'bg-[var(--surface-primary)]',
idClass: 'text-[#8BC9C1]',
}
);
@@ -299,7 +299,7 @@ export function ActivityPanel({ issues, collapsed = false, projectRoot }: Activi
const activeAgents = agentRoster.filter(a => a.status === 'active').length;
if (collapsed) {
return (
-
+
+
+
+// Dynamic paths
+
+
+// Remote URLs work too
+
+```
+
+
+ {frequencyData.map((amplitude, i) => (
+
+ ))}
+
+
+ );
+};
+```
+
+
+ {currentItem?.text ?? ''}
+
+ );
+};
+
+// Import SRT files
+import { parseSrt } from '@remotion/captions';
+const srtContent = await fetch(staticFile('captions.srt')).then(r => r.text());
+const captions = parseSrt(srtContent);
+```
+
+
+
+// Dynamic image sequence (frame-by-frame)
+
+
+// Conditional / data-driven
+
+```
+
+ {data.title}
;
+};
+```
+
+ Dynamic content
;
+};
+```
+
+
+ {/* content with transparent background */}
+
+
+
{/* Collapsed Agent Icons with ZFC Rings */}
{agentRoster.slice(0, 6).map(agent => (
@@ -316,7 +316,7 @@ export function ActivityPanel({ issues, collapsed = false, projectRoot }: Activi
agent.status === 'stale' ? 'ring-[#D4A574]/45' :
agent.status === 'stuck' ? 'ring-[#C97A7A]/45' : 'ring-[#A78A94]/40'
)}>
-
+
{getInitials(agent.name)}
@@ -340,9 +340,9 @@ export function ActivityPanel({ issues, collapsed = false, projectRoot }: Activi
}
return (
-
+
{/* AGENT ROSTER SECTION */}
-
+
@@ -368,7 +368,7 @@ export function ActivityPanel({ issues, collapsed = false, projectRoot }: Activi
getAgentTone(agent.status).glowClass
)} />
-
+
{getInitials(agent.name)}
diff --git a/src/components/activity/contextual-right-panel.tsx b/src/components/activity/contextual-right-panel.tsx
index b1831fd..5b7d1f9 100644
--- a/src/components/activity/contextual-right-panel.tsx
+++ b/src/components/activity/contextual-right-panel.tsx
@@ -1,6 +1,7 @@
'use client';
import React from 'react';
+import { ChevronLeft } from 'lucide-react';
import type { BeadIssue } from '../../lib/types';
import { ActivityPanel } from './activity-panel';
import { SwarmCommandFeed } from './swarm-command-feed';
@@ -15,9 +16,11 @@ export interface ContextualRightPanelProps {
swarmId?: string | null;
issues: BeadIssue[];
projectRoot: string;
+ actor?: string;
+ onMinimize?: () => void;
}
-export function ContextualRightPanel({ epicId, taskId, swarmId, issues, projectRoot }: ContextualRightPanelProps) {
+export function ContextualRightPanel({ epicId, taskId, swarmId, issues, projectRoot, actor, onMinimize }: ContextualRightPanelProps) {
const { setTaskId } = useUrlState();
// Task conversation takes priority — user explicitly clicked the conversation icon
@@ -32,6 +35,7 @@ export function ContextualRightPanel({ epicId, taskId, swarmId, issues, projectR
id={taskId}
issue={selectedIssue}
projectRoot={projectRoot}
+ actor={actor}
onIssueUpdated={async () => {}}
/>
);
@@ -58,10 +62,28 @@ export function ContextualRightPanel({ epicId, taskId, swarmId, issues, projectR
// Fallback to Global feed
return (
-
+ {onMinimize && (
+
);
}
diff --git a/src/components/activity/swarm-command-feed.tsx b/src/components/activity/swarm-command-feed.tsx
index 5976f14..93dfaa4 100644
--- a/src/components/activity/swarm-command-feed.tsx
+++ b/src/components/activity/swarm-command-feed.tsx
@@ -52,7 +52,24 @@ export function SwarmCommandFeed({ epicId, issues, projectRoot }: SwarmCommandFe
return entries;
}, [contextBeads, archetypes]);
- // 3. Subscribe to real-time activity, filtering ONLY for this epic's children
+ // 3. Load historical activity filtered to this epic's children
+ useEffect(() => {
+ if (contextBeadIds.size === 0) return;
+ async function loadHistory() {
+ try {
+ const res = await fetch(`/api/activity?projectRoot=${encodeURIComponent(projectRoot)}`);
+ if (!res.ok) return;
+ const data = (await res.json()) as ActivityEvent[];
+ const filtered = data.filter(e => e?.beadId && contextBeadIds.has(e.beadId));
+ setActivities(filtered.slice(0, 100));
+ } catch {
+ // ignore
+ }
+ }
+ void loadHistory();
+ }, [projectRoot, contextBeadIds]);
+
+ // 4. Subscribe to real-time activity, filtering ONLY for this epic's children
useEffect(() => {
const source = new EventSource(`/api/events?projectRoot=${encodeURIComponent(projectRoot)}`);
@@ -76,9 +93,9 @@ export function SwarmCommandFeed({ epicId, issues, projectRoot }: SwarmCommandFe
}, [projectRoot, contextBeadIds]);
return (
-
+ Live Activity Feed
+
+
+ )}
+
+
+
+
{/* SQUAD ROSTER SECTION */}
-
+
@@ -96,7 +113,7 @@ export function SwarmCommandFeed({ epicId, issues, projectRoot }: SwarmCommandFe
) : (
{rosterEntries.map((agent, i) => (
-
+
diff --git a/src/components/graph/graph-node-card.tsx b/src/components/graph/graph-node-card.tsx
index b676095..9935590 100644
--- a/src/components/graph/graph-node-card.tsx
+++ b/src/components/graph/graph-node-card.tsx
@@ -3,7 +3,7 @@
import { useState, useEffect, useRef } from 'react';
import { Handle, Position, type NodeProps, type Node } from '@xyflow/react';
import * as DropdownMenu from '@radix-ui/react-dropdown-menu';
-import { Loader2, ChevronDown, UserPlus, X, MessageSquare } from 'lucide-react';
+import { Columns2, Loader2, ChevronDown, Rocket, Signal, UserPlus, X, MessageSquare } from 'lucide-react';
import type { BeadIssue } from '../../lib/types';
import type { AgentArchetype } from '../../lib/types-swarm';
@@ -39,6 +39,12 @@ export interface GraphNodeData {
selectedTaskId?: string;
/** Opens the conversation panel for this node. Passed from UnifiedShell via WorkflowGraph. */
onConversationOpen?: (id: string) => void;
+ /** Navigates to the Social view with this task selected. */
+ onViewInSocial?: (id: string) => void;
+ /** Opens the Swarm Assignment panel for this task. */
+ onAssignMode?: (id: string) => void;
+ /** Restores the live telemetry feed in the right panel. */
+ onViewTelemetry?: (id: string) => void;
}
function getAssignedArchetypes(labels: string[], archetypes: AgentArchetype[]): AgentArchetype[] {
@@ -89,6 +95,9 @@ function nodeStyle(kind: GraphNodeData['kind']): string {
*/
export function GraphNodeCard({ id, data, selected }: NodeProps>) {
const onConversationOpen = data.onConversationOpen as ((id: string) => void) | undefined;
+ const onViewInSocial = data.onViewInSocial as ((id: string) => void) | undefined;
+ const onAssignMode = data.onAssignMode as ((id: string) => void) | undefined;
+ const onViewTelemetry = data.onViewTelemetry as ((id: string) => void) | undefined;
const isConvOpen = (data.selectedTaskId as string | undefined) === id;
const [hovered, setHovered] = useState(false);
const [isAssigning, setIsAssigning] = useState(false);
@@ -255,6 +264,46 @@ export function GraphNodeCard({ id, data, selected }: NodeProps
{assignedArchetypes.map((archetype) => (
diff --git a/src/components/graph/smart-dag.tsx b/src/components/graph/smart-dag.tsx
index 2efbef5..dcec2c5 100644
--- a/src/components/graph/smart-dag.tsx
+++ b/src/components/graph/smart-dag.tsx
@@ -2,6 +2,8 @@
import React, { useState, useMemo, useCallback } from 'react';
import { Filter, UserPlus } from 'lucide-react';
+import { useSearchParams, useRouter } from 'next/navigation';
+import { useUrlState, buildUrlParams } from '../../hooks/use-url-state';
import type { BeadIssue } from '../../lib/types';
import type { GraphHopDepth } from '../../lib/graph-view';
@@ -18,6 +20,7 @@ export interface SmartDagProps {
onSelectTask?: (id: string) => void;
projectRoot: string;
hideClosed?: boolean;
+ initialTab?: WorkflowTab;
onAssignModeChange?: (assignMode: boolean) => void;
onSelectedIssueChange?: (issue: BeadIssue | null) => void;
swarmId?: string;
@@ -32,14 +35,37 @@ export function SmartDag({
onSelectTask,
projectRoot,
hideClosed: hideClosedProp = false,
+ initialTab,
onAssignModeChange,
onSelectedIssueChange,
swarmId,
}: SmartDagProps) {
const { archetypes } = useArchetypes(projectRoot);
+ const { setTaskId } = useUrlState();
+ const searchParams = useSearchParams();
+ const router = useRouter();
+
+ // Single router.push so view AND task are set atomically — two separate calls
+ // would each rebuild from the same stale searchParams and the second would win.
+ const handleViewInSocial = useCallback((id: string) => {
+ const url = buildUrlParams(searchParams, { view: 'social', task: id, swarm: null, right: 'open', panel: 'open', drawer: null });
+ router.push(url, { scroll: false });
+ }, [searchParams, router]);
+
+ const handleNodeAssignMode = useCallback((_id: string) => {
+ setTaskId(null); // must clear task first so assignMode && !taskId renders AssignmentPanel
+ setAssignMode(true);
+ onAssignModeChange?.(true);
+ }, [onAssignModeChange, setTaskId]);
+
+ const handleNodeTelemetry = useCallback((_id: string) => {
+ setTaskId(null);
+ setAssignMode(false);
+ onAssignModeChange?.(false);
+ }, [onAssignModeChange, setTaskId]);
const [showFilters, setShowFilters] = useState(false);
- const [activeTab, setActiveTab] = useState('tasks');
+ const [activeTab, setActiveTab] = useState(initialTab ?? 'tasks');
const [assignMode, setAssignMode] = useState(false);
const [hideClosed, setHideClosed] = useState(true);
@@ -262,6 +288,9 @@ export function SmartDag({
beads={sortedTasks}
selectedId={selectedTaskId}
onSelect={onSelectTask}
+ onViewInSocial={handleViewInSocial}
+ onAssignMode={handleNodeAssignMode}
+ onViewTelemetry={handleNodeTelemetry}
hideClosed={hideClosed}
archetypes={archetypes}
assignMode={assignMode}
diff --git a/src/components/kanban/kanban-page.tsx b/src/components/kanban/kanban-page.tsx
index 8923ace..7e3540d 100644
--- a/src/components/kanban/kanban-page.tsx
+++ b/src/components/kanban/kanban-page.tsx
@@ -107,6 +107,7 @@ export function KanbanPage({
);
const graphHref = useMemo(() => {
const params = new URLSearchParams();
+ params.set('view', 'graph');
if (projectScopeMode !== 'single') {
params.set('mode', projectScopeMode);
}
@@ -114,7 +115,7 @@ export function KanbanPage({
params.set('project', projectScopeKey);
}
const query = params.toString();
- return query ? `/graph?${query}` : '/graph';
+ return query ? `/?${query}` : '/?view=graph';
}, [projectScopeKey, projectScopeMode]);
const allowMutations = projectScopeMode === 'single';
const blockedTree = useMemo(
diff --git a/src/components/sessions/conversation-drawer.tsx b/src/components/sessions/conversation-drawer.tsx
index ca002fd..d48f820 100644
--- a/src/components/sessions/conversation-drawer.tsx
+++ b/src/components/sessions/conversation-drawer.tsx
@@ -14,6 +14,47 @@ interface ThreadItem {
data: any;
}
+export type CoordMessageAction = 'read' | 'ack';
+
+export function buildCoordMessageActionEvent(params: {
+ action: CoordMessageAction;
+ message: AgentMessage;
+ beadId: string;
+ projectRoot: string;
+ nowIso?: string;
+}): Record {
+ const now = params.nowIso ?? new Date().toISOString();
+ const eventType = params.action === 'read' ? 'READ' : 'ACK';
+ const compactNow = now.replace(/[-:.TZ]/g, '');
+ return {
+ version: 'coord.v1',
+ kind: 'coord_event',
+ issue_id: params.beadId,
+ actor: params.message.to_agent,
+ timestamp: now,
+ data: {
+ event_type: eventType,
+ event_id: `evt_${eventType.toLowerCase()}_${compactNow}_${params.message.message_id}`,
+ event_ref: params.message.message_id,
+ project_root: params.projectRoot,
+ payload: {},
+ },
+ };
+}
+
+export function buildCommentMutationBody(params: {
+ projectRoot: string;
+ text: string;
+ actor?: string;
+}): Record {
+ const actor = params.actor?.trim();
+ return {
+ projectRoot: params.projectRoot,
+ text: params.text,
+ ...(actor ? { actor } : {}),
+ };
+}
+
interface ConversationDrawerProps {
beadId: string | null;
bead: BeadIssue | null;
@@ -26,6 +67,7 @@ interface ConversationDrawerProps {
onBackToAgent?: () => void;
embedded?: boolean;
refreshTrigger?: number;
+ actor?: string;
}
export function ConversationDrawer({
@@ -39,11 +81,13 @@ export function ConversationDrawer({
showAgentContext,
onBackToAgent,
embedded = false,
- refreshTrigger = 0
+ refreshTrigger = 0,
+ actor = '',
}: ConversationDrawerProps) {
const [thread, setThread] = useState([]);
const [loading, setLoading] = useState(false);
const [commentText, setCommentText] = useState('');
+ const [commentActor, setCommentActor] = useState(actor);
const [submitting, setSubmitting] = useState(false);
const [metrics, setMetrics] = useState(null);
const [showSummary, setShowSummary] = useState(false);
@@ -77,6 +121,10 @@ export function ConversationDrawer({
}
}, [agentId, projectRoot]);
+ useEffect(() => {
+ setCommentActor(actor);
+ }, [actor]);
+
useEffect(() => {
if (open) {
if (beadId) fetchConversation({ silent: refreshTrigger > 0 });
@@ -107,7 +155,7 @@ export function ConversationDrawer({
const res = await fetch(`/api/sessions/${beadId}/comment`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
- body: JSON.stringify({ projectRoot, text: commentText })
+ body: JSON.stringify(buildCommentMutationBody({ projectRoot, text: commentText, actor: commentActor })),
});
if (res.ok) {
setCommentText('');
@@ -127,8 +175,16 @@ export function ConversationDrawer({
if (!message) return;
try {
- const res = await fetch(`/api/sessions/${beadId}/messages/${messageId}/${action}?agent=${encodeURIComponent(message.to_agent)}`, {
- method: 'POST'
+ const event = buildCoordMessageActionEvent({
+ action,
+ message,
+ beadId,
+ projectRoot,
+ });
+ const res = await fetch('/api/coord/events', {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ projectRoot, event }),
});
if (res.ok) {
await fetchConversation();
@@ -259,6 +315,12 @@ export function ConversationDrawer({
{beadId && !showSummary && (