From c2e266870172312f461df75da3e7f6fbe9d2a1fc Mon Sep 17 00:00:00 2001
From: Maze Winther <mazewinther@gmail.com>
Date: Sun, 29 Mar 2026 12:53:37 +0200
Subject: [PATCH] docs: rewrite agents file

---
 AGENTS.md | 122 ++++--------------------------------------------------
 1 file changed, 9 insertions(+), 113 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 8ebac930..aef17c2e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,121 +1,17 @@
-# AGENTS.md
+# Agents.md
 
-## Overview
+## Apps
 
-Privacy-first video editor, with a focus on simplicity and ease of use.
+- Web
+- Desktop
 
-## Lib vs Utils
+## Rust
 
-- `lib/` - domain logic (specific to this app)
-- `utils/` - small helper utils (generic, could be copy-pasted into any other app)
+Shared code between apps live in `rust/`, not in `packages/`
 
-## Core Editor System
+## Web
 
-The editor uses a **singleton EditorCore** that manages all editor state through specialized managers.
+### React
 
-### Architecture
+- Read components before using them. They may already apply classes, which affects what you need to pass and how to override them.
 
-```
-EditorCore (singleton)
-├── playback: PlaybackManager
-├── timeline: TimelineManager
-├── scene: SceneManager
-├── project: ProjectManager
-├── media: MediaManager
-└── renderer: RendererManager
-```
-
-### When to Use What
-
-#### In React Components
-
-**Always use the `useEditor()` hook:**
-
-```typescript
-import { useEditor } from '@/hooks/use-editor';
-
-function MyComponent() {
-  const editor = useEditor();
-  const tracks = editor.timeline.getTracks();
-
-  // Call methods
-  editor.timeline.addTrack({ type: 'media' });
-
-  // Display data (auto re-renders on changes)
-  return <div>{tracks.length} tracks</div>;
-}
-```
-
-The hook:
-
-- Returns the singleton instance
-- Subscribes to all manager changes
-- Automatically re-renders when state changes
-
-#### Outside React Components
-
-**Use `EditorCore.getInstance()` directly:**
-
-```typescript
-// In utilities, event handlers, or non-React code
-import { EditorCore } from "@/core";
-
-const editor = EditorCore.getInstance();
-await editor.export({ format: "mp4", quality: "high" });
-```
-
-## Actions System
-
-Actions are the trigger layer for user-initiated operations. The single source of truth is `@/lib/actions/definitions.ts`.
-
-**To add a new action:**
-
-1. Add it to `ACTIONS` in `@/lib/actions/definitions.ts`:
-
-```typescript
-export const ACTIONS = {
-  "my-action": {
-    description: "What the action does",
-    category: "editing",
-    defaultShortcuts: ["ctrl+m"],
-  },
-  // ...
-};
-```
-
-2. Add handler in `@/hooks/use-editor-actions.ts`:
-
-```typescript
-useActionHandler(
-  "my-action",
-  () => {
-    // implementation
-  },
-  undefined,
-);
-```
-
-**In components, use `invokeAction()` for user-triggered operations:**
-
-```typescript
-import { invokeAction } from '@/lib/actions';
-
-// Good - uses action system
-const handleSplit = () => invokeAction("split-selected");
-
-// Avoid - bypasses UX layer (toasts, validation feedback)
-const handleSplit = () => editor.timeline.splitElements({ ... });
-```
-
-Direct `editor.xxx()` calls are for internal use (commands, tests, complex multi-step operations).
-
-## Commands System
-
-Commands handle undo/redo. They live in `@/lib/commands/` organized by domain (timeline, media, scene).
-
-Each command extends `Command` from `@/lib/commands/base-command` and implements:
-
-- `execute()` - saves current state, then does the mutation
-- `undo()` - restores the saved state
-
-Actions and commands work together: actions are "what triggered this", commands are "how to do it (and undo it)".