docs: improve documentation and add troubleshooting guide

Godzilla675 · Godzilla675 · commit b7b449653b48 · 2026-02-08T19:16:12.000Z
- Added docs/troubleshooting.md covering FFmpeg, MCP, and LLM issues.
- Updated docs/README.md to include troubleshooting and remove broken links.
- Updated docs/development.md with contribution guidelines and monorepo tips.
- Enhanced docs/api.md with Project JSON and WebSocket payload examples.
- Added troubleshooting link to root README.md.
diff --git a/README.md b/README.md
@@ -72,6 +72,10 @@ https://github.com/user-attachments/assets/f2d5a46b-36f4-4433-a7dc-18d0f2070d78
 - `pnpm dev:backend`: Start only backend
 - `pnpm build`: Build all packages
 
+## Troubleshooting
+
+Facing issues? Check our [Troubleshooting Guide](./docs/troubleshooting.md) for common solutions.
+
 ## Documentation
 
 For detailed documentation, please visit the [docs/](./docs/) directory:
diff --git a/docs/README.md b/docs/README.md
@@ -18,8 +18,8 @@ The editor leverages the power of GitHub Copilot and other AI models to provide
 - [MCP Tools & Servers](./mcp-tools.md) - A complete list of available AI tools and servers.
 - [Development Guide](./development.md) - How to set up, build, and contribute to the project.
 - [Security](./security.md) - Security considerations and sandboxing.
+- [Troubleshooting](./troubleshooting.md) - Common issues and solutions.
 
 ## Quick Links
 
 - [Root README](../README.md)
-- [Master Plan](../MASTERPLAN.MD)
diff --git a/docs/api.md b/docs/api.md
@@ -131,3 +131,93 @@ Broadcasts project updates to all connected clients.
   }
 }
 ```
+
+## Data Structures
+
+### Project JSON Example
+
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "name": "My Epic Video",
+  "created": "2024-01-26T12:00:00.000Z",
+  "modified": "2024-01-26T12:30:00.000Z",
+  "settings": {
+    "width": 1920,
+    "height": 1080,
+    "fps": 30
+  },
+  "timeline": {
+    "duration": 15,
+    "tracks": [
+      {
+        "id": "t1",
+        "type": "video",
+        "name": "Background",
+        "clips": [
+          {
+            "id": "c1",
+            "assetId": "a1",
+            "trackId": "t1",
+            "startTime": 0,
+            "duration": 10,
+            "sourceStart": 0,
+            "sourceEnd": 10,
+            "transform": { "x": 0, "y": 0, "scale": 1, "rotation": 0 }
+          }
+        ],
+        "muted": false,
+        "visible": true
+      }
+    ],
+    "markers": []
+  },
+  "assets": [
+    {
+      "id": "a1",
+      "name": "sunset.mp4",
+      "path": "/path/to/assets/sunset.mp4",
+      "type": "video",
+      "duration": 60
+    }
+  ]
+}
+```
+
+### WebSocket Message Payloads
+
+#### Sending a Message (`copilot.message`)
+```json
+{
+  "type": "copilot.message",
+  "payload": {
+    "content": "Add a 5 second clip of the sunset to the start of the video",
+    "projectId": "550e8400-e29b-41d4-a716-446655440000"
+  }
+}
+```
+
+#### Receiving a Tool Call (`copilot.tool_call`)
+```json
+{
+  "type": "copilot.tool_call",
+  "payload": {
+    "tool": "add_asset_to_project",
+    "args": {
+      "projectId": "550e8400-e29b-41d4-a716-446655440000",
+      "filePath": "/assets/sunset.mp4",
+      "type": "video"
+    }
+  }
+}
+```
+
+#### Project Update Broadcast (`project.updated`)
+```json
+{
+  "type": "project.updated",
+  "payload": {
+    "project": { ... } // Full project object
+  }
+}
+```
diff --git a/docs/development.md b/docs/development.md
@@ -70,3 +70,31 @@
 3. Extend `BaseMCPServer` from `@ai-video-editor/mcp-utils`.
 4. Register your tools.
 5. Add the server to the backend configuration in `apps/backend/src/mcp/server-configs.ts`.
+
+## Contributing
+
+We welcome contributions! Please follow these guidelines:
+
+### Branching Policy
+- Create a new branch for each feature or bug fix: `git checkout -b feature/your-feature-name`.
+- Use descriptive branch names.
+
+### Development Workflow
+1. **Fork the repository** (if you don't have push access).
+2. **Create a branch** for your changes.
+3. **Make your changes**. Ensure you follow the coding style and include tests where applicable.
+4. **Run linting**: `pnpm lint`.
+5. **Verify your changes**: Start the dev environment (`pnpm dev`) and test the functionality.
+6. **Submit a Pull Request**. Provide a clear description of your changes and why they are needed.
+
+### Monorepo Management
+This project uses **pnpm workspaces** and **Turbo**.
+- To add a dependency to a specific package: `pnpm add <package> --filter <package-name>`.
+- To run a command in all packages: `pnpm -r <command>`.
+- Common filters: `web`, `backend`, `ffmpeg-server`, `whisper-server`, etc.
+
+### Coding Standards
+- Use TypeScript for all new code.
+- Follow the existing indentation and formatting (Prettier/ESLint rules).
+- Document new functions and classes with JSDoc comments.
+- Ensure all public-facing API changes are reflected in `docs/api.md`.
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
@@ -0,0 +1,70 @@
+# Troubleshooting Guide
+
+This guide covers common issues you might encounter while setting up or running the AI Video Editor.
+
+## 1. FFmpeg Issues
+
+### FFmpeg not found
+**Symptoms**: Backend fails to start, or video processing tools return errors like "ffmpeg not found".
+**Solution**:
+- Ensure FFmpeg is installed on your system.
+- Add the FFmpeg binary directory to your system's PATH.
+- On macOS (Homebrew): `brew install ffmpeg`
+- On Ubuntu/Debian: `sudo apt update && sudo apt install ffmpeg`
+- On Windows: Download from [ffmpeg.org](https://ffmpeg.org/download.html) and add to Environment Variables.
+
+### FFmpeg version mismatch
+**Symptoms**: Errors during specific filtering or encoding operations.
+**Solution**: Ensure you are using FFmpeg 4.x or 5.x. Some advanced filters might require newer versions.
+
+## 2. MCP Server Connectivity
+
+### Server fails to connect
+**Symptoms**: Backend logs show "Failed to connect to MCP server [name]".
+**Solution**:
+- Check if the server's entry point exists. For example, `mcp-servers/ffmpeg-server/dist/index.js`.
+- If the `dist` folder is missing, run `pnpm build` from the project root.
+- Ensure the `node` command is available in your environment.
+
+### Tool execution timeout
+**Symptoms**: LLM reports a timeout or the backend logs show "Tool execution timed out".
+**Solution**:
+- Complex operations like `transcribe_audio` or `render_video` can take time.
+- Check system resources (CPU/RAM).
+- Increase the timeout in `apps/backend/src/mcp/client-manager.ts` if necessary.
+
+## 3. LLM & API Key Issues
+
+### 401 Unauthorized
+**Symptoms**: LLM provider returns an authentication error.
+**Solution**:
+- Double-check your API keys in `apps/backend/.env`.
+- Ensure there are no leading/trailing spaces in the keys.
+- If using GitHub Copilot, run `pnpm exec copilot` in `apps/backend` to re-authenticate.
+
+### Model not found
+**Symptoms**: Error stating "Model [name] not found".
+**Solution**:
+- Ensure the `LLM_MODEL` in your `.env` is supported by your provider and your specific API key tier.
+- Common models: `claude-3-5-sonnet-20240620`, `gpt-4o`, `gemini-1.5-pro`.
+
+## 4. Frontend & WebSocket Issues
+
+### WebSocket connection failed
+**Symptoms**: Frontend shows "Disconnected" or chat messages don't send.
+**Solution**:
+- Ensure the backend is running on the expected port (default 3001).
+- Check if `NEXT_PUBLIC_BACKEND_URL` in `apps/web/.env.local` matches your backend URL.
+- If running in a container or cloud environment, ensure WebSocket ports are exposed.
+
+### Mixed Content Errors
+**Symptoms**: Browser blocks requests to the backend.
+**Solution**: If the frontend is served over HTTPS, the backend must also be over HTTPS (WSS for WebSockets). For local development, HTTP/WS is fine.
+
+## 5. Whisper Server Issues
+
+### Model downloading fails
+**Symptoms**: Whisper server hangs or fails on the first transcription.
+**Solution**:
+- The first time it runs, it may attempt to download the Whisper model. Ensure you have an internet connection.
+- Check disk space. Models can be several hundred MBs to a few GBs.
