feat(docs): animated architecture overview video for contributors

.claude/skills/architecture-video/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: architecture-video
+description: Generate or update the IronClaw architecture overview video using Remotion. Use when asked to update, regenerate, or modify the architecture video, add/remove scenes, or reflect codebase changes in the video.
+---
+
+# Architecture Video Generator
+
+Generates and maintains the animated architecture overview video in `docs/architecture-video/` using Remotion (React-based video framework).
+
+## When to use
+
+- User asks to update, regenerate, or modify the architecture video
+- User asks to add or remove scenes from the video
+- Codebase architecture has changed and the video needs to reflect it
+- User wants to preview or render the video
+
+## Before making changes
+
+### 1. Read current architecture
+
+Read these files to understand the current system architecture:
+
+- `CLAUDE.md` — top-level project structure, module specs, key traits, principles
+- `crates/ironclaw_engine/CLAUDE.md` — engine v2 primitives, execution loop, CodeAct
+- `src/agent/CLAUDE.md` — agent loop architecture
+- `src/llm/CLAUDE.md` — LLM provider architecture
+- `src/db/CLAUDE.md` — database dual-backend architecture
+- `src/tools/README.md` — tool system architecture
+- `src/workspace/README.md` — workspace/memory architecture
+
+### 2. Read current video scenes
+
+Read `docs/architecture-video/src/IronClawArchitecture.tsx` to understand current scene order, durations, and transitions. Then read individual scenes in `docs/architecture-video/src/scenes/` to see what's already covered.
+
+### 3. Identify gaps
+
+Compare the architecture documentation with what the video covers. Look for:
+- New modules or traits added since the video was last updated
+- Renamed or restructured components
+- New data flows or state machines
+- Removed or deprecated features
+
+## Video project structure
+
+```
+docs/architecture-video/
+├── package.json              # Remotion deps
+├── remotion.config.ts        # Build config
+├── src/
+│   ├── Root.tsx              # Remotion entry — registers the composition
+│   ├── IronClawArchitecture.tsx  # Main composition — scene order + transitions
+│   ├── theme.ts              # Color palette + font constants
+│   ├── components/
+│   │   └── Code.tsx          # Syntax-highlighted code block component
+│   └── scenes/               # One file per scene
+│       ├── TitleScene.tsx
+│       ├── PrimitivesScene.tsx
+│       ├── ExecutionLoopScene.tsx
+│       ├── CodeActScene.tsx
+│       ├── ThreadStateScene.tsx
+│       ├── SkillsPipelineScene.tsx
+│       ├── ToolDispatchScene.tsx
+│       ├── ChannelsRoutingScene.tsx
+│       ├── ChannelImplsScene.tsx
+│       ├── TraitsScene.tsx
+│       ├── LlmDecoratorScene.tsx
+│       └── OutroScene.tsx
+```
+
+Render script: `scripts/render-architecture-video.sh`
+
+## Current scene inventory (12 scenes, ~82s at 30fps)
+
+| # | Scene | File | Duration | Content |
+|---|-------|------|----------|---------|
+| 1 | Title | TitleScene.tsx | 4s | Animated IronClaw logo + tagline |
+| 2 | Five Primitives | PrimitivesScene.tsx | 8s | Thread / Step / Capability / MemoryDoc / Project |
+| 3 | Execution Loop | ExecutionLoopScene.tsx | 8s | 7-step ExecutionLoop::run() pipeline |
+| 4 | CodeAct | CodeActScene.tsx | 10s | Python code → host fns → suspend/resume flow |
+| 5 | Thread State | ThreadStateScene.tsx | 7s | Created→Running⇄Waiting/Suspended→Completed/Failed→Done |
+| 6 | Skills Pipeline | SkillsPipelineScene.tsx | 8s | Gating → Scoring → Budget → Attenuation |
+| 7 | Tool Dispatch | ToolDispatchScene.tsx | 9s | 9-step ToolDispatcher::dispatch() pipeline |
+| 8 | Channels Routing | ChannelsRoutingScene.tsx | 7s | Channel trait + stream::select_all merging |
+| 9 | Channel Impls | ChannelImplsScene.tsx | 7s | REPL / HTTP / Web / Signal / TUI / WASM |
+| 10 | Traits | TraitsScene.tsx | 8s | 8 traits with concrete implementers |
+| 11 | LLM Decorators | LlmDecoratorScene.tsx | 7s | SmartRouting→CircuitBreaker→...→Base decorator chain |
+| 12 | Outro | OutroScene.tsx | 5s | Start Contributing + getting-started steps |
+
+## Remotion patterns used in this project
+
+All animations MUST be driven by `useCurrentFrame()` — never CSS transitions or Tailwind animation classes.
+
+### Animation pattern
+
+```tsx
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+const opacity = interpolate(frame, [0, 0.5 * fps], [0, 1], {
+  extrapolateRight: "clamp",
+});
+const y = interpolate(frame, [0, 0.5 * fps], [30, 0], {
+  extrapolateRight: "clamp",
+  easing: Easing.bezier(0.16, 1, 0.3, 1),
+});
+```
+
+### Staggered list pattern
+
+For items that appear one by one:
+
+```tsx
+{items.map((item, i) => {
+  const delay = 0.4 + i * 0.3; // seconds
+  const opacity = interpolate(
+    frame,
+    [delay * fps, (delay + 0.35) * fps],
+    [0, 1],
+    { extrapolateLeft: "clamp", extrapolateRight: "clamp" }
+  );
+  return <div style={{ opacity }} key={item.id}>...</div>;
+})}
+```
+
+### Scene transitions
+
+Scenes are composed using `TransitionSeries` with alternating `fade()` and `slide({ direction: "from-right" })` transitions, each 15 frames (0.5s):
+
+```tsx
+<TransitionSeries>
+  <TransitionSeries.Sequence durationInFrames={s(8)}>
+    <MyScene />
+  </TransitionSeries.Sequence>
+  <TransitionSeries.Transition
+    presentation={fade()}
+    timing={linearTiming({ durationInFrames: 15 })}
+  />
+  <TransitionSeries.Sequence durationInFrames={s(7)}>
+    <NextScene />
+  </TransitionSeries.Sequence>
+</TransitionSeries>
+```
+
+### Code blocks
+
+Use the `CodeBlock` component from `../components/Code` for syntax-highlighted code:
+
+```tsx
+import { CodeBlock } from "../components/Code";
+
+<CodeBlock code={`pub trait Channel: Send + Sync {
+  async fn start(&self) -> Result<MessageStream>;
+}`} fontSize={13} />
+```
+
+### Theme
+
+Import colors and fonts from `../theme`:
+
+```tsx
+import { COLORS, FONTS } from "../theme";
+
+// Available colors:
+// bg, bgLight, primary, primaryLight, accent, accentLight,
+// success, danger, text, textMuted, border, purple, cyan, pink
+
+// Available fonts:
+// mono (monospace), sans (system-ui)
+```
+
+## Adding a new scene
+
+1. Create `src/scenes/MyNewScene.tsx` following existing patterns
+2. Export the component
+3. Import in `IronClawArchitecture.tsx`
+4. Add to the `SCENES` array with duration and transition type
+5. `TOTAL_DURATION` auto-computes from the array
+6. Verify with: `npx remotion still IronClawArchitecture --scale=0.25 --frame=<N>`
+
+### Scene template
+
+```tsx
+import {
+  AbsoluteFill,
+  interpolate,
+  useCurrentFrame,
+  useVideoConfig,
+  Easing,
+} from "remotion";
+import { COLORS, FONTS } from "../theme";
+
+export const MyNewScene: React.FC = () => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+
+  const headingOpacity = interpolate(frame, [0, 0.4 * fps], [0, 1], {
+    extrapolateRight: "clamp",
+  });
+
+  return (
+    <AbsoluteFill
+      style={{
+        backgroundColor: COLORS.bg,
+        fontFamily: FONTS.sans,
+        padding: 60,
+      }}
+    >
+      <div
+        style={{
+          opacity: headingOpacity,
+          fontSize: 42,
+          fontWeight: 700,
+          color: COLORS.text,
+          marginBottom: 4,
+        }}
+      >
+        <span style={{ color: COLORS.primary }}>Title</span> — subtitle
+      </div>
+      {/* Scene content */}
+    </AbsoluteFill>
+  );
+};
+```
+
+## Verification
+
+After making changes:
+
+1. **Type check:** `cd docs/architecture-video && npx tsc --noEmit`
+2. **Spot check frames:** `npx remotion still IronClawArchitecture --scale=0.25 --frame=<N>`
+   - At 30fps, frame N corresponds to time N/30 seconds
+   - Check at least one frame per modified scene
+3. **Full render:** `./scripts/render-architecture-video.sh [output-path]`
+4. **Preview in browser:** `cd docs/architecture-video && npm run dev`
+
+## Design guidelines
+
+- Dark theme (slate-900 background) — matches typical developer tooling
+- Each scene has a colored heading keyword using a trait-appropriate color
+- File:line references in muted monospace below headings
+- Data flows use staggered animation (0.3-0.5s delays between items)
+- State machines use SVG with animated dash-offset for arrows
+- Code blocks use the `CodeBlock` component with syntax highlighting
+- Keep scene duration proportional to content density (7-10s typical)
+- Total video should stay under 120s for attention retention

Cargo.toml

@@ -27,6 +27,7 @@ rust-version = "1.92"
 description = "Secure personal AI assistant that protects your data and expands its capabilities on the fly"
 authors = ["NEAR AI <support@near.ai>"]
 license = "MIT OR Apache-2.0"
+publish = false
 homepage = "https://github.com/nearai/ironclaw"
 repository = "https://github.com/nearai/ironclaw"
 

docs/architecture-video/.gitignore

@@ -0,0 +1,7 @@
+node_modules
+dist
+.DS_Store
+.env
+
+# Ignore the output video from Git but not videos you import into src/.
+out

docs/architecture-video/.prettierrc

@@ -0,0 +1,5 @@
+{
+  "useTabs": false,
+  "bracketSpacing": true,
+  "tabWidth": 2
+}

docs/architecture-video/README.md

@@ -0,0 +1,54 @@
+# Remotion video
+
+<p align="center">
+  <a href="https://github.com/remotion-dev/logo">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://github.com/remotion-dev/logo/raw/main/animated-logo-banner-dark.apng">
+      <img alt="Animated Remotion Logo" src="https://github.com/remotion-dev/logo/raw/main/animated-logo-banner-light.gif">
+    </picture>
+  </a>
+</p>
+
+Welcome to your Remotion project!
+
+## Commands
+
+**Install Dependencies**
+
+```console
+npm i
+```
+
+**Start Preview**
+
+```console
+npm run dev
+```
+
+**Render video**
+
+```console
+npx remotion render
+```
+
+**Upgrade Remotion**
+
+```console
+npx remotion upgrade
+```
+
+## Docs
+
+Get started with Remotion by reading the [fundamentals page](https://www.remotion.dev/docs/the-fundamentals).
+
+## Help
+
+We provide help on our [Discord server](https://discord.gg/6VzzNDwUwV).
+
+## Issues
+
+Found an issue with Remotion? [File an issue here](https://github.com/remotion-dev/remotion/issues/new).
+
+## License
+
+Note that for some entities a company license is needed. [Read the terms here](https://github.com/remotion-dev/remotion/blob/main/LICENSE.md).

docs/architecture-video/eslint.config.mjs

@@ -0,0 +1,3 @@
+import { config } from "@remotion/eslint-config-flat";
+
+export default config;