@hybridlabor-api/bdb-antigravity-skills 1.2.1 → 1.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hybridlabor-api/bdb-antigravity-skills",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "Optimized Antigravity skills and MCP pack for BDB DEV",
   "main": "installer.js",
   "bin": {

package/skills/global_config/bdb-adobe-suite-mcp.md

@@ -0,0 +1,106 @@
+---
+name: bdb-adobe-suite-mcp
+description: Utilizes the Adobe Suite MCP servers (adobe_mcp.py and adobe_uxp_mcp) to automate Photoshop, Illustrator, Premiere Pro, and After Effects using ExtendScript and UXP WebSocket bridges.
+---
+
+# Adobe Creative Suite MCP — Integration and AI Guide
+
+This skill file instructs AI agents on how to control Adobe Creative Suite applications (Photoshop, Illustrator, After Effects, and Premiere Pro) using both ExtendScript (`adobe_mcp.py`) and UXP WebSocket (`adobe_uxp_mcp`) bridges.
+
+## 1. Overview and Pipeline Value
+
+The **Adobe Suite MCP integrations** combine two distinct automation strategies for Creative Cloud applications:
+1. **ExtendScript Bridge (`adobe_mcp.py`):** Uses OS-level scripting (AppleScript `osascript` on macOS; PowerShell COM objects on Windows) to send JSX code directly to Photoshop, Illustrator, and After Effects. This runs without installing plugins.
+2. **UXP (Unified Extensibility Platform) Bridge (`adobe_uxp_mcp`):** Connects to Photoshop and Premiere Pro via a local WebSocket server (default port `8080`). This provides modern, fast, and sandboxed JS API interactions but requires UXP developer plugins to be active in the application.
+
+---
+
+## 2. System Instructions
+
+### Tool Selection Matrix
+When asked to automate Photoshop, choose between the two interfaces based on application state:
+- If UXP plugins are connected, use `adobe-uxp-mcp` tools (`ps_get_active_document`, `ps_add_layer`).
+- If UXP is unavailable, fall back to ExtendScript tools (`ps_add_text_layer`).
+
+### OS Platform Routing
+The ExtendScript bridge dynamically routes script payloads:
+- **macOS:** Targets application bundle IDs (e.g. `id "com.adobe.Photoshop"`) using AppleScript `do javascript` / `DoScript`.
+- **Windows:** Instantiates COM interfaces (e.g., `Photoshop.Application`, `Illustrator.Application`, `AfterFX.Application`) using PowerShell and processes transient `.jsx` scripts.
+
+---
+
+## 3. Available Tools and API Parameters
+
+### ExtendScript Tools (`adobe_mcp.py`)
+- **`ps_add_text_layer(text: string, font_size?: int)`**: Adds a new text layer with contents to the active Photoshop file.
+- **`ae_render_active_comp()`**: Appends the active composition to the After Effects render queue and kicks off the render.
+- **`ai_draw_rectangle(width?: float, height?: float, red?: int, green?: int, blue?: int)`**: Spawns a document in Illustrator (if empty) and draws a filled path rectangle.
+
+### UXP Tools (`adobe_uxp_mcp`)
+- **`ps_get_active_document`**: Retrieves the file name of the frontmost document in Photoshop.
+- **`ps_add_layer(name: string)`**: Adds a new layer in Photoshop.
+- **`pr_get_active_sequence`**: Retrieves the active sequence name from the Premiere Pro project.
+
+---
+
+## 4. Code Recipes and Prompt Cookbook
+
+### Recipe 1: Draw Custom Vector Layout in Illustrator
+Generate a filled RGB path inside Adobe Illustrator via the ExtendScript bridge:
+
+```json
+// Tool Call: ai_draw_rectangle
+{
+  "width": 500.0,
+  "height": 250.0,
+  "red": 0,
+  "green": 128,
+  "blue": 255
+}
+```
+
+### Recipe 2: UXP Photoshop Layer Control
+Retrieve the active document name, check context, and add a layer via UXP:
+
+```json
+// Step 1: Read active file name
+// Tool Call: ps_get_active_document
+
+// Step 2: Create a layer named "Background_Tint"
+// Tool Call: ps_add_layer
+{
+  "name": "Background_Tint"
+}
+```
+
+### Recipe 3: Batch rendering a composition (After Effects ExtendScript)
+Queue and render:
+
+```json
+// Tool Call: ae_render_active_comp
+{}
+```
+
+---
+
+## 5. Troubleshooting and Connection Details
+
+### Configuration and Ports
+- **UXP WebSocket Port:** `8080` (Standard WebSocket connection `ws://localhost:8080`)
+- **Bridge Setup:**
+  - *ExtendScript:* Requires zero installation beyond standard macOS or Windows system settings.
+  - *UXP Server:* Start the server (`node mcps/adobe_uxp_mcp/index.js`). Then open Photoshop/Premiere and load the respective plugin folder located in `mcps/adobe_uxp_mcp/plugins/` using the **Adobe UXP Developer Tool (UDT)**.
+
+### Common Errors and Fixes
+1. **`Adobe Application is not connected to the UXP MCP Bridge`**
+   - *Cause:* The UXP plugin has not been loaded via the UXP Developer Tool.
+   - *Fix:* Launch the Adobe UXP Developer Tool, click **Add Plugin**, navigate to `mcps/adobe_uxp_mcp/plugins/photoshop/manifest.json`, and click **Load**.
+2. **`COM Object Instantiation Failed (Windows)`**
+   - *Cause:* Adobe software is not registered correctly in the Windows Registry, or is running with different privilege elevations.
+   - *Fix:* Ensure the targeted Adobe application is open and registered. Run your CLI terminal with administrator privileges if User Account Control (UAC) blocks COM access.
+3. **`osascript User interaction is not allowed`**
+   - *Cause:* macOS Accessibility permissions are blocking terminal commands from driving GUI applications.
+   - *Fix:* Add Terminal / Cursor / Claude to **Accessibility** and **Automation** folders in Privacy & Security settings.
+4. **`Port 8080 already in use`**
+   - *Cause:* The UXP WebSocket server conflicts with a running Docker container or Web developer server.
+   - *Fix:* Edit the `WS_PORT` constant inside `adobe_uxp_mcp/index.js` and matching plugin configs to utilize an alternate port (e.g. `8888`).

package/skills/global_config/bdb-after-effects-mcp.md

@@ -0,0 +1,117 @@
+---
+name: bdb-after-effects-mcp
+description: Utilizes the After Effects MCP servers (after-effects-mcp and ae-mcp) to create compositions, layers, masks, keyframe animations, and run ExtendScript.
+---
+
+# After Effects MCP — Integration and AI Agent Guide
+
+This skill file instructs AI agents on how to control Adobe After Effects using the Node.js `after-effects-mcp` and Go `ae-mcp` integrations. It details ExtendScript scripting, layer manipulation, keyframe animation, and troubleshooting steps.
+
+## 1. Overview and Pipeline Value
+
+The **After Effects MCP Server** integrations enable AI assistants to programmatically control Adobe After Effects (2022+). They automate title design, motion graphics layouts, layer adjustments, mask path generations, and visual effects pipelines.
+
+### Architecture
+- **JSX Script Bridge:** Because After Effects lacks a native REST API, control is achieved using an ExtendScript (`.jsx`) panel.
+- **`after-effects-mcp` (Node.js):** Writes commands to a local temp file. An AE panel script (`mcp-bridge-auto.jsx`) polls this file every few seconds, executes the script via AE's JavaScript engine, and writes the output back to disk.
+- **`ae-mcp` (Go):** Exposes similar ExtendScript bridges and includes a **Manim Integration** to render mathematical equations using Python's Manim package and import them into AE as transparent WebP animations.
+
+---
+
+## 2. System Instructions
+
+### Workflow Priorities
+1. **Enable Scripting Preferences:** After Effects must have **"Allow Scripts to Write Files and Access Network"** enabled (`Preferences -> Scripting & Expressions`).
+2. **Verify the Bridge Panel is Open:** Ensure the `mcp-bridge-auto.jsx` panel is loaded in After Effects (`Window -> mcp-bridge-auto.jsx`) and that the "Auto-run commands" checkbox is checked. Without it, commands will hang.
+3. **Handle coordinates safely:** After Effects uses a 2D coordinate system originating from the top-left corner `[0,0]` of the active composition.
+4. **ExtendScript Fallback:** If a high-level tool cannot perform a complex layer relationship task, write a custom script and execute it via the `run-script` tool.
+
+---
+
+## 3. Available Tools and API Parameters
+
+### Node-based `after-effects-mcp` Tools
+
+| Tool | Parameters | Description |
+| :--- | :--- | :--- |
+| **`create-composition`** | `name: string`, `width: int`, `height: int`, `frameRate: float`, `duration: float` | Spawns a new comp in the active project. |
+| **`run-script`** | `script: string` | Evaluates arbitrary ExtendScript code inside the AE DOM. |
+| **`get-results`** | None | Reads the result of the last executed script. |
+| **`setLayerProperties`** | `layerIndex: int`, `properties: object` | Adjusts position `[x,y,z]`, scale `[x,y,z]`, opacity, rotation, 3D status, or blendMode. |
+| **`setLayerKeyframe`** | `layerIndex: int`, `propertyName: string`, `time: float`, `value: any` | Creates a keyframe on a layer property at a specified timeline position. |
+| **`setLayerExpression`** | `layerIndex: int`, `propertyName: string`, `expression: string` | Binds a Javascript expression to a target property (e.g. `wiggle(5, 20)`). |
+| **`createCamera`** | `name: string`, `zoom: float` | Adds a 3D camera layer to the active composition. |
+| **`setLayerMask`** | `layerIndex: int`, `maskName: string`, `points: float[][]` | Configures mask paths, feathering, expansion, and opacity. |
+
+### Go-based `ae-mcp` Tools
+- Includes identical layer creation wrappers.
+- **`generate-manim-render(code: string)`**: Executes Python Manim to render math equations and imports them as WebP clips into the project assets folder.
+
+---
+
+## 4. Code Recipes and Prompt Cookbook
+
+### Recipe 1: Standard Kinetic Typography
+Create a composition, add a text layer, center it, and apply a scale wiggle expression:
+
+```json
+// Step 1: Create Comp
+// Tool: create-composition(name="TitleAnimation", width=1920, height=1080, frameRate=29.97, duration=5.0)
+
+// Step 2: Write ExtendScript to add a text layer
+// Tool: run-script(script="var comp = app.project.activeItem; var textLayer = comp.layers.addText('HELLO BDB OS'); textLayer.property('Position').setValue([960, 540]);")
+
+// Step 3: Apply Wiggle to Scale
+// Tool: setLayerExpression(layerIndex=1, propertyName="Scale", expression="wiggle(2, 15)")
+```
+
+### Recipe 2: Custom Text Ingest from File
+To batch-generate subtitles or title cards using `run-script`:
+
+```javascript
+// Call tool: run-script(script="...")
+var comp = app.project.activeItem;
+if (comp && comp instanceof CompItem) {
+    app.beginUndoGroup("Create Titles");
+    var titles = ["Design", "Develop", "Deploy"];
+    for (var i = 0; i < titles.length; i++) {
+        var textLayer = comp.layers.addText(titles[i]);
+        textLayer.property("Position").setValue([960, 200 + (i * 200)]);
+        textLayer.startTime = i * 1.5;
+        textLayer.outPoint = (i + 1) * 1.5;
+    }
+    app.endUndoGroup();
+    "Successfully created " + titles.length + " text layers.";
+} else {
+    "Error: No active composition.";
+}
+```
+
+---
+
+## 5. Troubleshooting and Connection Details
+
+### Configuration and Setup
+- **ExtendScript Panel:** The bridge operates via `mcp-bridge-auto.jsx`.
+- **Install Panel:**
+  ```bash
+  # run installer script from the after-effects-mcp folder
+  npm run install-bridge
+  ```
+  This places the script inside After Effects' ScriptUI Panels folder.
+- **Active Communication:** Node MCP runs locally using standard stdio. Ensure the client config file is properly wired up:
+  ```json
+  "AfterEffectsMCP": {
+    "command": "node",
+    "args": ["/Users/timrennings/bdb-dev-optimized-antigravity-skills/mcps/after-effects-mcp/build/index.js"]
+  }
+  ```
+
+### Common Errors and Fixes
+1. **`Adobe Script Error: Security setting does not allow this script to write files`**
+   - *Fix:* In After Effects, go to `Preferences -> Scripting & Expressions` and check the box **"Allow Scripts to Write Files and Access Network"**.
+2. **`Commands are hanging / No response from server`**
+   - *Cause:* The bridge UI panel is closed in After Effects, or the "Auto-run" checkbox is disabled.
+   - *Fix:* Navigate to `Window -> mcp-bridge-auto.jsx` in the top menu and verify that the panel is open and actively polling (indicated by status prints in the panel window).
+3. **`ExtendScript undefined variable or Layer index out of bounds`**
+   - *Cause:* ExtendScript arrays in After Effects are **1-indexed** for layers (`comp.layer(1)`) while the Node tools layer indices might be 0-indexed depending on the tool call translation. Ensure you map boundaries carefully.

package/skills/global_config/bdb-blender-mcp.md

@@ -0,0 +1,130 @@
+---
+name: bdb-blender-mcp
+description: Utilizes the Blender MCP server and addon to build 3D assets, apply materials, inspect scenes, and script bpy.
+---
+
+# Blender MCP — Integration and AI Agent Guide
+
+This skill file instructs AI agents on how to interact with the Blender MCP server and addon. It details scene manipulation, Python code execution (`bpy`), external asset retrieval, and troubleshooting workflows.
+
+## 1. Overview and Pipeline Value
+
+The **Blender MCP Server** connects AI models to Blender (3.0+) via a local TCP socket bridge. In the BDB OS workflow, this integration speeds up low-poly layouts, scene prototyping, material assignment, rendering, and programmatic asset generation.
+
+### Architecture
+- **Blender Addon (`addon.py`):** Runs inside Blender, creating a socket server (default port `9876`) that executes incoming requests on Blender's main thread using the Blender Python API (`bpy`).
+- **MCP Server Bridge:** A Node.js or Python-based subprocess (`blender-mcp`) connecting to the addon socket, presenting a clean tool layout to the AI.
+- **Generative AI & API Integrations:** Integrates with Poly Haven (materials, HDRIs, models), Sketchfab, Hyper3D Rodin, and Hunyuan3D for AI-assisted asset drafting.
+
+---
+
+## 2. System Instructions
+
+### Workflow Priorities
+1. **Connect First:** Ensure Blender is open and the MCP Addon is actively running (click "Connect to Claude" in the Sidebar's **BlenderMCP** tab).
+2. **Read the Scene:** Proactively query the active scene layout using introspection tools before placing meshes.
+3. **Save Work Proactively:** Running arbitrary script commands can crash the active Blender session. Always instruct the user to back up their project before running custom code.
+4. **Clean Code Structure:** When using `execute_blender_code`, write standard `bpy` script blocks. Delete reference meshes (like the default Cube) programmatically if the prompt asks for a clean slate.
+
+---
+
+## 3. Available Tools and API Parameters
+
+| Tool | Parameters | Description |
+| :--- | :--- | :--- |
+| **`get_scene_info`** | None | Returns document structure, active camera, render settings, and a list of all scene objects. |
+| **`create_mesh`** | `type: string`, `location?: float[]`, `scale?: float[]`, `rotation?: float[]`, `name?: string` | Spawns primitive shapes: Cube, Sphere, Cylinder, Cone, Torus, Grid, Monkey, Plane. |
+| **`delete_object`** | `name: string` | Removes a named object from the database. |
+| **`modify_object`** | `name: string`, `location?: float[]`, `scale?: float[]`, `rotation?: float[]` | Applies transformations to objects. |
+| **`create_material`** | `name: string`, `color: float[]`, `metallic?: float`, `roughness?: float` | Creates and configures a Principled BSDF material. |
+| **`apply_material`** | `object_name: string`, `material_name: string` | Binds a material to a target mesh. |
+| **`execute_blender_code`** | `code: string` | Evaluates arbitrary Python scripts in Blender using the full `bpy` library. |
+| **`search_polyhaven`** | `query: string`, `type: string` | Queries HDRIs, textures, or models from the Poly Haven API. |
+| **`import_polyhaven_asset`** | `asset_id: string`, `type: string` | Downloads and imports Poly Haven items directly into the viewport. |
+| **`generate_hyper3d_model`** | `prompt: string` | Triggers Hyper3D Rodin API to draft a model and load it. |
+
+---
+
+## 4. Code Recipes and Prompt Cookbook
+
+### Recipe 1: Standard Material Setup and Assignment
+Create a metallic red material and assign it to a newly spawned cylinder:
+
+```json
+// Step 1: Create the cylinder
+// Tool: create_mesh(type="cylinder", location=[0, 0, 2], name="RedColumn")
+
+// Step 2: Create red material
+// Tool: create_material(name="MetallicRed", color=[0.8, 0.05, 0.05, 1.0], metallic=0.9, roughness=0.1)
+
+// Step 3: Apply to object
+// Tool: apply_material(object_name="RedColumn", material_name="MetallicRed")
+```
+
+### Recipe 2: Run Custom Python Script via execute_blender_code
+Generate a procedural spiral of spheres using `bpy`:
+
+```python
+# Call tool: execute_blender_code(code="...")
+import bpy
+import math
+
+# Clear default objects
+bpy.ops.object.select_all(action='SELECT')
+bpy.ops.object.delete(use_global=False)
+
+# Build spiral
+count = 30
+radius = 5.0
+height_step = 0.2
+angle_step = 0.3
+
+for i in range(count):
+    angle = i * angle_step
+    x = math.cos(angle) * radius
+    y = math.sin(angle) * radius
+    z = i * height_step
+    
+    # Add sphere
+    bpy.ops.mesh.primitive_uv_sphere_add(radius=0.5, location=(x, y, z))
+    sphere = bpy.context.active_object
+    sphere.name = f"SpiralSphere_{i}"
+```
+
+---
+
+## 5. Troubleshooting and Connection Details
+
+### Configuration and Ports
+- **Default TCP Port:** `9876` (Bypasses stdio when communicating with the Blender Addon).
+- **Environment Variables:**
+  - `BLENDER_HOST`: Local/remote address of the Blender application (default: `localhost`).
+  - `BLENDER_PORT`: Port number of the socket listener (default: `9876`).
+
+### Telemetry Control
+To disable usage telemetry, set the environment variable:
+```bash
+DISABLE_TELEMETRY=true
+```
+Or toggle the Consent checkbox in the Addon settings inside Blender:
+`Edit -> Preferences -> Add-ons -> Interface: Blender MCP`
+
+### Connection Verification
+Ensure the Blender Addon is actively listening on port `9876`:
+```bash
+# Check if Blender is holding the socket
+lsof -i :9876
+```
+
+### Common Errors and Fixes
+1. **`Cannot connect to Blender Addon at localhost:9876`**
+   - *Cause:* The addon is installed but not running, or connection was closed.
+   - *Fix:* In Blender, press `N` to open the sidebar, click the **BlenderMCP** tab, and toggle **Connect to Claude** ON.
+2. **`Missing API Keys for Hyper3D or Sketchfab`**
+   - *Fix:* Add the API keys directly in the Add-on preferences page in Blender (`Edit -> Preferences -> Add-ons -> Blender MCP`) or inject them as environment variables (e.g. `BLENDERMCP_HYPER3D_API_KEY`) prior to starting the MCP client.
+3. **`execute_blender_code fails due to Context`**
+   - *Cause:* Blender operators (`bpy.ops`) often require a specific active context (e.g., Edit Mode vs Object Mode, or an active selection).
+   - *Fix:* Ensure your Python script sets the active object or overrides context if necessary before executing operators:
+     ```python
+     bpy.context.view_layer.objects.active = target_obj
+     ```

package/skills/global_config/bdb-computer-use-mcp.md

@@ -0,0 +1,119 @@
+---
+name: bdb-computer-use-mcp
+description: Utilizes the computer-use-mcp server to control the OS desktop via mouse, keyboard, window focus, accessibility trees, and scripting.
+---
+
+# Computer Use MCP — Integration and AI Agent Guide
+
+This skill file instructs AI agents on how to control macOS, Windows, or Linux desktop environments using the high-performance `computer-use-mcp` server. It details tool hierarchy, accessibility automation, scripting, window focus strategies, and troubleshooting steps.
+
+## 1. Overview and Pipeline Value
+
+The **Computer Use MCP Server** leverages a Rust NAPI module to interact directly with OS APIs (CoreGraphics/AppKit on Mac; Win32/COM on Windows; X11 on Linux). It serves as the ultimate fallback when structured application APIs do not exist. Agents use it to configure settings, install dependencies, click modal dialogs, copy coordinates, and interact with graphical interfaces.
+
+### Architecture
+- **In-Process native execution:** Avoids shell hopping by using direct OS calls inside Node.js.
+- **Ordered Automation:**
+  1. *Scripting first:* Use AppleScript/JXA (macOS) or PowerShell (Windows).
+  2. *Accessibility second:* Query and interact with elements using Accessibility APIs (AX UI Automation).
+  3. *Coordinate Clicks last:* Use screenshots and pixel coordinates only as a fallback.
+
+---
+
+## 2. System Instructions
+
+### Workflow Priorities
+1. **Discovery first:** Always call `get_tool_guide` or `get_app_capabilities` to evaluate if the target app supports AppleScript/PowerShell or Accessibility trees.
+2. **Accessibility over Coordinates:** Use `click_element` or `set_value` instead of mapping pixel coordinates from a screenshot. It survives window resizes, retina scaling, and display moves.
+3. **Window Focus Strategies:** 
+   - Use `strict` focus for keyboard inputs. This forces the server to verify the target window is frontmost and visible before typing, preventing key drops.
+   - Use `prepare_display` to automatically hide background apps that might steal focus or pop up notifications during execution.
+4. **Retroactive Inspection:** If a screenshot shows small text or dense detail, call `zoom` with a cropped coordinate box to view full-resolution assets.
+
+---
+
+## 3. Available Tools and API Parameters
+
+Exposes 58 native tools. Key tools include:
+
+### Discovery and Scripting
+- **`get_tool_guide(task_description: string)`**: Plans if JXA, AppleScript, AX UI Automation, or pixel click is recommended.
+- **`run_script(language: string, script: string)`**: Executes JXA, AppleScript, or PowerShell.
+- **`get_app_capabilities(bundle_id: string)`**: Queries scriptable, accessible, or active state.
+
+### Accessibility (AX UI Automation)
+- **`get_ui_tree(target_app?: string, target_window_id?: int)`**: Returns a JSON structure of active UI roles and labels.
+- **`click_element(role: string, label: string)`**: Performs a semantic click on a button or menu.
+- **`set_value(role: string, label: string, value: string)`**: Sets values in text fields directly.
+- **`fill_form(fields: array, target_app?: string)`**: Sets multiple text fields in a single call.
+- **`list_menu_bar(bundle_id: string)`**: Lists menu items and keyboard shortcuts.
+
+### Mouse and Keyboard
+- **`screenshot(width?: int, quality?: int, target_window_id?: int)`**: Captures the viewport.
+- **`left_click(coordinate: int[], target_app?: string)`**: Simulates a left-click.
+- **`type(text: string, press_enter?: boolean, target_app?: string)`**: Enters text.
+- **`key(text: string, target_app?: string)`**: Triggers combinations (e.g. `command+s`).
+
+### Windows and Displays
+- **`list_windows(bundle_id?: string)`**: Queries all visible windows.
+- **`activate_window(window_id: int)`**: Places focus on a targeted window.
+- **`list_spaces()`**: Interacts with macOS Spaces or Windows Virtual Desktops.
+
+---
+
+## 4. Code Recipes and Prompt Cookbook
+
+### Recipe 1: Retrieve and Interact with Photoshop AX Tree
+Instead of taking a screenshot and clicking coordinates, find the "New Layer" button semantically:
+
+```json
+// Step 1: Probe Photoshop Capabilities
+// Tool: get_app_capabilities(bundle_id="com.adobe.Photoshop")
+
+// Step 2: Get Window list to target the correct window ID
+// Tool: list_windows(bundle_id="com.adobe.Photoshop")
+
+// Step 3: Semantic Click on the New Layer Button
+// Tool: click_element(role="AXButton", label="New Layer", target_app="com.adobe.Photoshop")
+```
+
+### Recipe 2: Run JXA (Javascript for Automation) Script on macOS
+Create a new note in Apple Notes and write text programmatically:
+
+```javascript
+// Tool: run_script(language="javascript", script="...")
+// Script content:
+var Notes = Application("Notes");
+var newNote = Notes.Note({
+    body: "<h1>BDB OS Integration Checklist</h1><p>Automated desktop test complete.</p>"
+});
+Notes.folders.byName("Notes").notes.push(newNote);
+Notes.activate();
+```
+
+---
+
+## 5. Troubleshooting and Connection Details
+
+### Configuration and Setup
+- **MacOS Permissions Required:** You must grant **Accessibility** access to the parent application (e.g. Terminal, Cursor, or Claude Desktop) in `System Settings -> Privacy & Security -> Accessibility`.
+- **Linux Packages Required:** 
+  ```bash
+  sudo apt-get install -y xdotool wmctrl xclip scrot
+  ```
+
+### Common Errors and Fixes
+
+1. **`FocusFailure: Target window is not frontmost`**
+   - *Cause:* The `strict` focus strategy detected another application stole active focus.
+   - *Fix:* Switch your `focus_strategy` to `prepare_display` to auto-hide background applications, or call `activate_window` first.
+2. **`spawn uvx ENOENT / command not found`**
+   - *Cause:* The client (GUI) did not inherit terminal shell PATH settings.
+   - *Fix:* Configure your client to use the absolute path of `npx` or wrap it with `cmd /c` on Windows:
+     ```json
+     "command": "npx",
+     "args": ["--yes", "--prefer-offline", "@zavora-ai/computer-use-mcp"]
+     ```
+3. **`Accessibility tree AXError: API Disabled`**
+   - *Cause:* System Sandbox is blocking accessibility inspector calls.
+   - *Fix:* Relaunch the parent application (Cursor/Claude Code) and verify the Accessibility toggle is active in your OS System Preferences.

package/skills/global_config/bdb-davinci-mcp.md

@@ -0,0 +1,139 @@
+---
+name: bdb-davinci-mcp
+description: Utilizes the DaVinci Resolve MCP servers to control timeline editing, media analysis, color grading, and Fusion/Fairlight scripting.
+---
+
+# DaVinci Resolve MCP — Integration and AI Agent Guide
+
+This skill file instructs AI agents on how to interface with the DaVinci Resolve MCP Server integrations (including `davinci-resolve-mcp` and `davinci-mcp-professional`). It details page requirements, media analysis, edit loops, versioning pipelines, and troubleshooting steps.
+
+## 1. Overview and Pipeline Value
+
+The **DaVinci Resolve MCP Server** exposes the complete scripting API of DaVinci Resolve Studio (18.5 to 21+) to AI models. In the BDB OS workflow, this server acts as an intelligent assistant that can automate timeline assembly, perform source-safe audio/video analysis, manage color grade metadata (CDLs/LUTs/stills), write timeline markers, and compile extension scripts.
+
+### Architecture
+- **Local Scripting API:** Communicates with Resolve via the official external Python scripting interface.
+- **Two Operational Modes:**
+  - *Compound Mode (Default):* Exposes 32 structured tools containing 136 guarded workflow kernels. Keeps the model's context footprint lean.
+  - *Granular Mode (`--full`):* Exposes 341 tools representing a one-to-one mapping of every Resolve scripting API method.
+- **Local Control Panel:** Includes a browser dashboard (`venv/bin/python -m src.control_panel`) for visual inspection, timeline rollback, and manual analysis review.
+
+---
+
+## 2. System Instructions
+
+### Page Requirements
+Resolve is page-centric. Many tool calls will fail if the application is on the wrong page. Always verify or transition the page before invoking page-specific tools:
+
+| Workflow | Page Required | Transition Command |
+| :--- | :--- | :--- |
+| **Media Ingest / Bins** | Media | `resolve_control(action="open_page", params={"page": "media"})` |
+| **Timeline Assembly / Edits** | Edit or Cut | `resolve_control(action="open_page", params={"page": "edit"})` |
+| **Color Grading / LUTS / CDL** | Color | `resolve_control(action="open_page", params={"page": "color"})` |
+| **Audio Configuration** | Fairlight | `resolve_control(action="open_page", params={"page": "fairlight"})` |
+| **Effects / Compositing** | Fusion | `resolve_control(action="open_page", params={"page": "fusion"})` |
+| **Render Setup / Queues** | Deliver | `resolve_control(action="open_page", params={"page": "deliver"})` |
+
+### Media Analysis and Visual Verification (host_chat_paths)
+1. **Source Media Safety:** Never transcode, modify, or create derivatives of original camera files. Write report files only to the `davinci-resolve-mcp-analysis` scratch directory.
+2. **Visual Analysis Flow:** 
+   - `analyze_clip` or `analyze_bin` extracts keyframes to disk and returns a deferred payload with `frame_paths` and a verification token.
+   - The AI agent must read these image frames, generate a structured description, and finalize the analysis by calling `media_analysis(action="commit_vision", params={clip_id, visual, vision_token})`.
+   - **Do not skip `commit_vision`**; doing so leaves the clip in a `pending_host_vision_analysis` error state.
+
+### Evidence-Based Editing (`edit_engine`)
+Every timeline edit operates on a **Plan → Confirm → Execute** loop:
+- `plan_tighten` or `plan_selects` calculates trims (e.g., dead air removal from transcription evidence) and returns a `plan_id`.
+- The user must review this plan (optionally via the browser UI).
+- Run `execute_tighten(plan_id)` with a verification token to write the edits to a new timeline version.
+
+---
+
+## 3. Available Tools and API Parameters
+
+Key tools on the compound server include:
+
+| Tool | Action | Parameters | Description |
+| :--- | :--- | :--- | :--- |
+| **`resolve_control`** | `launch`, `get_page`, `open_page`, `api_truth`, `quit` | `page?: string` | Manages active page contexts and Resolve application states. |
+| **`project_manager`** | `list`, `get_current`, `create`, `load`, `save`, `import_project`, `export_project`, `lint`, `apply_spec` | `name?: string`, `path?: string`, `spec?: object` | Handles project CRUD, backup archives, health linting, and declarative YAML specs. |
+| **`media_pool`** | `get_clips`, `import_media`, `move_clips`, `setup_multicam_timeline`, `get_selected` | `paths?: string[]`, `target_path?: string` | Organizes media pool folders, imports files, and sets up multi-cam stacks. |
+| **`media_pool_item`** | `get_metadata`, `set_metadata`, `get_clip_property`, `set_clip_color`, `get_audio_mapping` | `clip_id: string`, `key: string`, `value?: any` | Sets search tags, notes, track mapping, and clip colors in Resolve. |
+| **`media_analysis`** | `plan`, `coverage_report`, `analyze_clip`, `detect_sync_events`, `publish_clip_metadata`, `commit_vision`, `build_embeddings`, `find_similar` | `clip_id?: string`, `kinds?: string[]`, `vision_token?: string` | Handles visual keyframing, audio transcriptions, sync detection, and semantic vector indexing. |
+| **`edit_engine`** | `plan_selects`, `execute_selects`, `plan_tighten`, `execute_tighten`, `plan_swap`, `execute_swap` | `plan_id?: string`, `timeline_name?: string`, `alternate_index?: int` | Plans and executes video trimming, select reels, and alternate take swaps. |
+| **`timeline_versioning`** | `begin_run`, `end_run`, `archive_current`, `list_versions`, `diff_versions`, `diff_timelines` | `timeline_name?: string`, `reason?: string` | Records edit logs, structures version diffs, and rolls back edits. |
+| **`script_plugin`** | `run_inline`, `execute`, `safe_install_extension`, `safe_remove_extension` | `source: string`, `language: string` | Authoring utility that runs or installs custom Lua/Python script extensions. |
+
+---
+
+## 4. Code Recipes and Prompt Cookbook
+
+### Recipe 1: CDL Grade Backup and Export
+Snapshot a clip's grade, inspect CDL, and export a look:
+
+```json
+// Step 1: Switch to Color page
+// Tool: resolve_control(action="open_page", params={"page": "color"})
+
+// Step 2: Snapshot active item's grade
+// Tool: timeline_item_color(action="grade_version_snapshot", params={"version_name": "BeforeAdjustment"})
+
+// Step 3: Set CDL parameters for mild primary grade adjustment
+// Tool: timeline_item_color(action="safe_set_cdl", params={"slope": [1.05, 1.0, 0.95], "offset": [0.01, 0.0, -0.01]})
+```
+
+### Recipe 2: Run Inline Scripting for Batch Meta Change
+Use `run_inline` to quickly rename clips matching a specific prefix inside the Media Pool:
+
+```json
+// Tool: script_plugin(action="run_inline", params={"language": "python", "source": "..."})
+// Source value:
+import sys
+resolve = BmdResolveAPI()
+projectManager = resolve.GetProjectManager()
+project = projectManager.GetCurrentProject()
+mediaPool = project.GetMediaPool()
+rootFolder = mediaPool.GetRootFolder()
+
+def rename_clips(folder):
+    for clip in folder.GetClipList():
+        name = clip.GetName()
+        if name.startswith("CAM_A_"):
+            clip.SetClipProperty("Clip Name", name.replace("CAM_A_", "AngleA_"))
+    for subfolder in folder.GetSubFolderList():
+        rename_clips(subfolder)
+
+rename_clips(rootFolder)
+print("Rename complete")
+```
+
+---
+
+## 5. Troubleshooting and Connection Details
+
+### Configuration and Ports
+- **Application Port:** Controlled via system environment variables. Resolve communicates natively with the local Python runtime.
+- **Control Panel Dashboard:** `http://localhost:5000` (by default) or path printed upon running:
+  ```bash
+  venv/bin/python -m src.control_panel
+  ```
+- **Requirements:**
+  1. **DaVinci Resolve Studio** (Scripting APIs are blocked in the free version).
+  2. **External Scripting Mode:** Go to DaVinci Resolve -> Preferences -> System -> General, set "External scripting using" to **Local** or **Developer**.
+  3. **Python Registry (Windows):** Python must be installed system-wide for Resolve to find it in the registry (pyenv or virtual environments will not work if the host installer isn't registered).
+
+### Diagnostic Connection Verification
+Test if the local Python bridge can reach Resolve:
+```bash
+# Verify the Python scripting modules are discoverable
+python -c "import DaVinciResolveScript as dvr; print(dvr.scriptapp('Resolve'))"
+```
+
+### Common Errors
+1. **`Resolve is not running or scripting is disabled`**
+   - Ensure the Studio version is active.
+   - Verify that preferences are set to "External scripting using: Local".
+2. **`Visual Analysis stuck in pending_host_vision_analysis`**
+   - The agent has not called the `commit_vision` tool with the results of visual frame descriptions. Check the manifest files in your scratch analysis directory to recover the token.
+3. **`Fusion.Execute() returns False or no-op`**
+   - Resolve 20+ has limitations with remote execution of Lua scripts. Use the `run_inline` tool which leverages a temporary file fallback mechanism.