Adom Bridge (macOS)

@@ -534,599 +534,6 @@ Two generic CLI commands exist for launching any executable or app safely - they - `adom-bridge launch '{"path":"...", "args":[...], "cwd":"...", "detached":true}'` -- Same resolution rules as `find_exe`, then spawns. Fails in terminal (exit 1) with a clear error if the path doesn't exist. **Always prefer this over a raw shell `open`.**  For Fusion specifically, use `fusion_start` - it wraps `launch` plus the full startup-picker / add-in-readiness dance.-- `fusion_import_step` -- Import a STEP/STL/IGES file into Fusion 360-- `fusion_open_lbr` -- Open an EAGLE .lbr library file-- `fusion_open_electronics` -- Check if the Electronics workspace is active-- `fusion_electron_run` -- Execute any EAGLE command via Electron.run. Returns rich state: `activeWorkspace`, `activeDocument`, `commandType`, `_hint`, and `fusionOperations` (diff of Fusion's internal operation log showing what actually fired). **Avoid blocking commands** - see list below. **Full EAGLE command reference:** [`skills/eagle-commands.md`](./eagle-commands.md) - popular/safe commands split from blocking/modal ones, with layer reference and chaining syntax.-- `fusion_execute_text_command` -- Low-level app.executeTextCommand() access. Returns the command result plus workspace context.-- `fusion_board_info` -- Get structured board data from the open PCB layout. Returns: component placements (name, package, x, y, rotation), net names, copper traces, layer setup, board thickness, DRC violations. Much richer than a screenshot - gives exact coordinates and connectivity. Requires a .brd board open in PCB Editor.--#### `fusion_electron_run` - EAGLE Command Execution--Executes EAGLE commands inside Fusion 360's Electronics workspace. Works in **Schematic Editor**, **PCB Editor (Board Layout)**, and **Electronics Library** contexts.--**How it works:** Sends the command string via Fusion's `Electron.run` text command. EAGLE's `Electron.run` is fire-and-forget - it never returns output or throws on invalid commands. To compensate, the handler snapshots Fusion's internal operation log (`Diagnostics.RecentOperations`) before and after execution, returning a diff showing what actually fired.--**Usage:**-```bash-# Basic command-adom-bridge fusion_electron_run '{"command": "WINDOW FIT"}'--# Multiple commands in sequence (use semicolons)-adom-bridge fusion_electron_run '{"command": "DISPLAY NONE; DISPLAY 1 16 17 18 20 21"}'--# Navigate in library editor-adom-bridge fusion_electron_run '{"command": "EDIT SOIC8.pac"}'-adom-bridge fusion_electron_run '{"command": "EDIT RESISTOR.sym"}'-adom-bridge fusion_electron_run '{"command": "EDIT MYDEVICE.dev"}'-```--**Response fields:**-- `activeWorkspace` - Current workspace (Schematic Editor, PCB Editor, Electronics Library)-- `activeDocument` - Name of the open document-- `commandType` - Detected type: `view_control`, `layer_control`, `edit`, `design_rule`, etc.-- `editorType` - For EDIT commands: `package`, `symbol`, `device`-- `fusionOperations` - Array of Fusion operations that fired (diff of internal log)-- `hint` - Human-readable description of what happened-- `rawResult` - Raw return from Electron.run (usually empty)--**EAGLE Command Reference - Safe for automation:**--| Command | Context | Description |-|---------|---------|-------------|-| **View / Navigation** | | |-| `WINDOW FIT` | Any | Zoom to fit all content |-| `WINDOW (x1 y1 x2 y2)` | Any | Zoom to specific area (coordinates in current units) |-| `DISPLAY ALL` | Any | Show all layers |-| `DISPLAY NONE` | Any | Hide all layers |-| `DISPLAY 1 16 17 18 20 21` | Board | Show specific layers by number |-| **Grid** | | |-| `GRID MM 0.1` | Any | Set grid to 0.1mm |-| `GRID MIL 25` | Any | Set grid to 25mil |-| `GRID INCH 0.05` | Any | Set grid to 0.05 inch |-| **Board Layout** | | |-| `RATSNEST` | Board | Recalculate airwires (unrouted connections) |-| `RIPUP` | Board | Remove all routed traces |-| `RIPUP *` | Board | Remove all traces (same as RIPUP with no selection) |-| `ROUTE` | Board | Start auto-router |-| `DRC` | Board | Run design rule check |-| `BOARD` | Schematic | Switch to paired board layout |-| `SCHEMATIC` | Board | Switch to paired schematic |-| **Schematic** | | |-| `VALUE value` | Schematic | Set component value |-| `NAME name` | Any | Rename selected element |-| `SMASH` | Any | Detach name/value labels from components |-| **Library Editor** | | |-| `EDIT name.pac` | Library | Open a package (footprint) for editing |-| `EDIT name.sym` | Library | Open a symbol for editing |-| `EDIT name.dev` | Library | Open a deviceset for editing |-| `EXPORT SCRIPT 'path.scr'` | Library | Export entire library as EAGLE script |-| **Scripting / Settings** | | |-| `SET CONFIRM YES` | Any | Suppress confirmation dialogs |-| `SET CONFIRM OFF` | Any | Re-enable confirmation dialogs |-| `SCRIPT 'path.scr'` | Any | Run batch commands from a .scr script file |--**EAGLE Layer Numbers (commonly used):**--| Layer | Name | What it shows |-|-------|------|--------------|-| 1 | Top | Top copper |-| 16 | Bottom | Bottom copper |-| 17 | Pads | Through-hole pads |-| 18 | Vias | Via holes |-| 19 | Unrouted | Airwires (ratsnest) |-| 20 | Dimension | Board outline (required for 3D) |-| 21 | tPlace | Top silkscreen |-| 22 | bPlace | Bottom silkscreen |-| 25 | tNames | Top component names |-| 27 | tValues | Top component values |-| 29 | tStop | Top solder mask |-| 31 | tCream | Top stencil/paste |-| 51 | tDocu | Top documentation |--**Blocking commands - AVOID from automation:**--| Command | Why it blocks |-|---------|---------------|-| `WRITE` | Opens Save As dialog - use `fusion_save_lbr` or `fusion_close_document` instead |-| `ADD` | Opens component picker dialog |-| `SHOW name` | Opens interactive highlight mode |-| `SET` (no params) | Opens settings dialog |-| `GRID` (no params) | Opens grid settings dialog |-| `EDIT new.sym` | Opens "Create new?" confirmation if symbol doesn't exist |-| `CHANGE` | Opens interactive change mode |-| `MOVE` | Opens interactive move mode |--**Tips:**-- Always run `WINDOW FIT` after opening a file or switching views-- Use `DISPLAY NONE` then `DISPLAY <layers>` to show only specific layers-- Combine commands with `;` - e.g., `SET CONFIRM YES; RIPUP *; RATSNEST`-- For board screenshots: `DISPLAY NONE; DISPLAY 1 16 17 18 20 21; WINDOW FIT`-- Use `fusion_board_info` instead of EAGLE commands when you need structured data-- `fusion_export_lbr` -- Export the open Electronics library as an EAGLE .scr script (note: does NOT include 3D package references - those are cloud-linked only)-- `fusion_save_lbr` -- Save the open Electronics library as a .flbr file--#### EAGLE Libraries with 3D Packages--Fusion 360's .lbr format supports `package3d` elements that link footprints to 3D models. Key facts:--- **3D models are cloud-hosted** - each `package3d` has a `wip_urn` (e.g., `urn:adsk.wipprod:fs.file:vf.xxxxx`) pointing to a Fusion cloud document. You cannot embed STEP files directly in .lbr XML.-- **Creating 3D packages requires the Fusion UI** - use `Package3DCreateCmd` in Electronics Library Editor, which opens a new Design workspace where you model/import the 3D shape, then save to link it.-- **`EXPORT SCRIPT` strips 3D references** - the .scr export only contains 2D data (symbols, footprints, devicesets). To preserve 3D links, keep the .lbr XML format.-- **Fusion's built-in examples** have 3D packages - 34 of 37 libraries in the EAGLE examples directory (e.g., `Connector_USB.lbr`, `Resistor.lbr`, `Capacitor.lbr`) include `package3d` references.-- **Example libraries location** (macOS): under the Fusion install's `.../Applications/Electron/LibEagle/examples/libraries/examples/` (find the install with `find_exe` or ask the bridge; the webdeploy hash changes per build)--To open a built-in example library for reference:-```bash-# Find the examples directory first-adom-bridge fusion_execute_text_command '{"command": "Python.RunScript /tmp/find_eagle_libs.py"}'-# Then open one-adom-bridge fusion_open_lbr '{"filePath": "<path>/Connector_USB.lbr"}'-```-- `fusion_open_schematic` -- Open a .sch schematic in Fusion's Schematic Editor. Args: `filePath`.-- `fusion_open_board` -- Open a .brd board layout in Fusion's Board Layout editor. Args: `filePath`.-- `fusion_show_3d_board` -- Switch to 3D PCB board view (must have a .brd open). Board MUST have an outline on layer 20 (Dimension) or 3D generation fails. Auto-zooms to fit after switching.-- `fusion_show_2d_board` -- Switch back to 2D board layout from 3D PCB view. EAGLE commands via `fusion_electron_run` only work in 2D.-- `fusion_close_document` -- Close a document without save dialog. Args: `name` (optional, defaults to active doc), `save` (optional, default false). Essential for automation - avoids modal save dialog that blocks Fusion.-- `fusion_document_info` -- List ALL open documents/tabs with name, type, and active status, plus detailed cloud info for the active document. Returns `openDocuments` array (every tab) and active doc details (cloud project, folder, file ID, version, save status). Lightweight - uses only in-memory data, no cloud API calls. Use this instead of `fusion_walk_cloud_tree` when you just need to know what's open.-- `fusion_activate_document` -- Switch to a specific open document tab. Args: `name` (substring match, case-insensitive), `documentType` ("Electronics", "PCB", "FusionDesign", "Drawing"). Essential for automation - switch between schematic, board, and library tabs without user interaction. If no match found, returns the list of open documents so you can refine.-- `fusion_close` -- Close Fusion 360. **Always call this when done with Fusion 360 commands to clean up.**-- `fusion_dismiss_recovery` -- Dismiss recovery document dialogs (both "Recovered Documents" list and "Open recovery document instead?" prompts). Also relocates recovery files to `~/.adom/recovery/fusion/` for safekeeping.-- `fusion_relocate_recovery` -- Proactively move Fusion crash recovery files to `~/.adom/recovery/fusion/<timestamp>/` without dismissing any dialogs. Call this **before** launching Fusion to prevent recovery dialogs from appearing. Files are preserved (not deleted) so the user can manually restore them if needed.-- `fusion_close_all_documents` -- Close all open documents. Args: `saveChanges` (default: false). Use before force-killing Fusion to prevent recovery files.--#### Fusion 360 UI Interaction--Commands for interacting with Fusion 360's UI - detecting dialogs, taking screenshots, clicking, and sending keyboard input. Essential for handling blocking dialogs and automating CEF-based UI elements.--- `fusion_window_info` -- Returns the Fusion main window HWND, title, rect, and a list of all Qt dialog windows (recovery dialogs, wizards, file pickers). Essential for detecting blocking dialogs before/after operations.-  - Example: `adom-bridge fusion_window_info`-  - Returns: `{hwnd, title, rect, dialogs: [{hwnd, title, className, rect}]}`--- `fusion_screenshot_fusion` -- Captures the Fusion main window or a specific dialog by window id. Background capture (works without bringing to foreground). Saves WebP to `/tmp/adom-bridge-screenshots/` (falls back to PNG if WebP unavailable). Downscaled to ≤1568px - use relative coords (0.0-1.0) for clicking, they're scale-independent. DPI-aware.-  - Args: `hwnd` (optional - dialog HWND to screenshot instead of main window)-  - Example: `adom-bridge fusion_screenshot_fusion` (main window)-  - Example: `adom-bridge fusion_screenshot_fusion '{"hwnd": 12345}'` (specific dialog)--- `fusion_screenshot_all` -- Screenshots the main Fusion window and lists all dialog windows with their HWNDs. Use `fusion_screenshot_fusion {"hwnd": ...}` to capture each dialog.-  - Example: `adom-bridge fusion_screenshot_all`--- `fusion_click_fusion` -- Click at coordinates within the Fusion window or a specific dialog. x/y are relative (0.0-1.0) by default. Set `"relative": false` for pixel offsets. Uses synthetic OS input for CEF dialog compatibility. **Prefer `fusion_send_key` for dialogs** - enter/escape/tab covers most cases.-  - Args: `x` (required), `y` (required), `relative` (optional, default true), `hwnd` (optional - target a specific dialog HWND instead of main window)-  - Example: `adom-bridge fusion_click_fusion '{"x": 0.5, "y": 0.7}'` (main window)-  - Example: `adom-bridge fusion_click_fusion '{"hwnd": 12345, "x": 0.75, "y": 0.85}'` (dialog button)--- `fusion_send_key` -- Send keyboard input to Fusion or a specific dialog via synthetic OS input. **Preferred way to dismiss dialogs**: enter to confirm, escape to cancel, tab to cycle buttons. Use click only if tab order doesn't reach the right button.-  - Args: `key` (required), `hwnd` (optional - target a specific dialog HWND)-  - Example: `adom-bridge fusion_send_key '{"key": "escape"}'` (dismiss CEF dialog)-  - Example: `adom-bridge fusion_send_key '{"key": "enter", "hwnd": 12345}'` (confirm dialog)--#### Fusion 360 Workflow Guide--##### Opening Electronics Projects-1. Open the `.fprj` file: `adom-bridge fusion_open_cloud_file '{"projectName":"Main","fileName":"DRV8411A","fileExtension":"fprj","folderPath":"Molecules/XRP/DRV8411A"}'`-2. Do NOT try to open `.fbrd` or `.fsch` directly - they fail or show a "Select Electronics Design File" dialog-3. Enter the board editor: `adom-bridge fusion_show_2d_board`-4. Enter the schematic editor: After step 3, use `adom-bridge fusion_electron_run '{"command":"EDIT .sch"}'`-5. Switch back to board: `adom-bridge fusion_electron_run '{"command":"EDIT .brd"}'`--##### Auto-Screenshot on Open Commands--**Open commands automatically screenshot Fusion and return the images in the response.** The following commands include `postOpenScreenshot` in their `data` field:-- `fusion_open_cloud_file`, `fusion_open_schematic`, `fusion_open_board`, `fusion_show_3d_board`, `fusion_show_2d_board`--The response `data.postOpenScreenshot` contains:-- `screenshots[]` - array of `{type, savedTo, sizeKB, title?, hwnd?}`. Type is `"main_window"` or `"dialog"`.-- `message` - human-readable instruction to READ each screenshot and check for blocking dialogs-- `dialogBlocking` - `true` if a modal dialog was detected--**After receiving the response, you MUST:**-1. **READ each screenshot file** using the Read tool to visually inspect what Fusion shows-2. Look for blocking dialogs in the screenshots:-   - "What to design?" wizard → dismiss with `fusion_send_key {"key": "escape"}`-   - "PCB out of date" banner → click Update or X-   - "Recovered Documents" → `fusion_dismiss_recovery`-   - "Save changes?" → `fusion_send_key {"key": "escape"}`-   - Any other modal → identify and dismiss-3. **Screenshot again** after dismissing to confirm it's clear--Screenshots are saved as WebP (lossless, ~20-40KB each, downscaled to ≤1568px) for token efficiency. Both the main Fusion window AND all Qt dialog windows are captured separately.--**Why this matters**: Fusion shows Qt dialogs and CEF overlays that are invisible to the API. The `success: true` response from an open command does NOT mean the UI is ready - a dialog may be blocking all further operations. The API cannot detect these. Only a screenshot can.--##### Detecting and Handling Blocking Dialogs-- The auto-screenshot captures dialog windows separately (look for `type: "dialog"` entries in `postOpenScreenshot.screenshots[]`)-- Common blocking dialogs: "What do you want to design?", "Recovered Documents", "Open recovery document instead?", "Select Electronics Design File"-- Dismiss recovery dialogs: `adom-bridge fusion_dismiss_recovery`-- Dismiss CEF dialogs (inside main window): `adom-bridge fusion_send_key '{"key": "escape"}'` or `fusion_click_fusion`-- Dismiss "What do you want to design?" wizard: `adom-bridge fusion_send_key '{"key": "escape"}'`-- For manual screenshot of specific dialogs: `adom-bridge desktop_screenshot_window '{"hwnd": <DIALOG_HWND>}'`--##### Preventing Recovery Documents-- Recovery files are at: `~/Library/Application Support/Autodesk/Autodesk Fusion 360/<USER_ID>/CrashRecovery/`-- Before force-killing Fusion, close all documents: `adom-bridge fusion_close_all_documents '{"saveChanges": false}'`-- **Best practice**: Call `adom-bridge fusion_relocate_recovery` before launching Fusion. This moves recovery files to `~/.adom/recovery/fusion/<timestamp>/` - preserving them for the user while preventing modal dialogs.-- The `fusion_start` command also auto-relocates recovery files before starting Fusion.-- The `fusion_dismiss_recovery` command handles both "Recovered Documents" list and "Open recovery document instead?" prompts, and also relocates files.--##### EAGLE Export Limitations-- **Supported**: `EXPORT IMAGE`, `EXPORT NETLIST`, `EXPORT PARTLIST`-- **NOT supported** (fail silently): `EXPORT DXF`, `EXPORT SVG`, `EXPORT DRILL`-- Always verify export output: the updated `fusion_electron_run` now checks if the output file was created-- Use `fusion_export_bom` and `fusion_export_cpl` for manufacturing data (these use the add-in's XML parser, not EAGLE export)-- Use `fusion_export_gerbers` for Gerber files - produces a ZIP with all gerber layers (GTL, GBL, GTS, GBS, GTP, GBP, GTO, GBO, GKO, XLN). Auto-detects 2-layer vs 4-layer boards.--##### 3D Model Exports-- From the 3D view (activate the .f3d document): `fusion_export_step`, `fusion_export_stl`, `fusion_export_3mf`, `fusion_export_f3d`, `fusion_export_usdz`, `fusion_export_iges`, `fusion_export_sat`-- Switch to 3D view: `fusion_show_3d_board` or activate the .f3d document-- **STEP** - Industry-standard CAD interchange (SolidWorks, CATIA, Creo). Highest geometric fidelity.-- **IGES** - Legacy CAD interchange. Use STEP for modern workflows.-- **SAT** - ACIS solid model format. Used by SolidWorks, SpaceClaim.-- **STL** - Mesh format for 3D printing and visualization. Options: refinement "low"/"medium"/"high".-- **3MF** - Modern 3D printing with color/material support and multi-body.-- **F3D** - Native Fusion 360 archive. Preserves parametric features, sketches, timeline, component refs. Best for archival.-- **USDZ** - **Best for digital twins and GLB conversion.** Preserves full component hierarchy (Board, copper layers, soldermask, Packages), PBR materials, and named nodes. Each component becomes a toggleable node in GLB viewers. Also viewable directly on iOS/macOS (Apple Quick Look / AR).-  - Digital twin pipeline: `fusion_export_usdz` → pull_file → `blender --background --python-expr "import bpy; bpy.ops.wm.usd_import(filepath='board.usdz'); bpy.ops.export_scene.gltf(filepath='board.glb')"`-- **FBX** - Not available in current Fusion builds via the API. The command exists but fails clearly. Use `fusion_export_usdz` instead.-- **DXF/DWG/OBJ/SKP** - Not available via the Fusion API (dialog-only). Commands exist but return clear errors with alternatives.--##### 3D Viewport Captures-- `fusion_take_screenshot` - Capture the Fusion viewport at any resolution without opening a dialog. Uses Fusion's render API (`saveAsImageFile`).-  - Args: `outputPath` (required), `width` (default 1920), `height` (default 1080), `orientation` (optional)-  - Orientations: `home`, `front`, `back`, `top`, `bottom`, `left`, `right`-  - Example: Capture all 6 standard views for use as product images/icons:-    ```bash-    for orient in home front back top bottom left right; do-      adom-bridge fusion_take_screenshot "{\"outputPath\": \"/tmp/3d-${orient}.png\", \"width\": 1920, \"height\": 1080, \"orientation\": \"${orient}\"}"-    done-    ```--##### Electronics Source File Export (`fusion_export_source`)-- `fusion_export_source` - Export the active electronics document as `.fsch`, `.fbrd`, or `.flbr` source file.-  - Args: `outputPath` (required - full path with extension)-  - The extension determines the format: `.fsch` (schematic), `.fbrd` (board), `.flbr` (library)-  - Validates extension, creates output directory, verifies file was created, returns file size--- **Full workflow to export both board and schematic from a cloud project:**-  ```bash-  # Step 1: Open the .fprj (NOT .fbrd/.fsch directly - those fail)-  adom-bridge fusion_open_cloud_file '{"projectName":"Main", "fileName":"MyDesign", "fileExtension":"fprj", "folderPath":"Molecules/MyDesign"}'--  # Step 2: Screenshot to check for blocking dialogs (always do this after open)-  adom-bridge fusion_screenshot_fusion--  # Step 3: Enter board view (MUST be Board Layout workspace, not 3D)-  adom-bridge fusion_show_2d_board--  # Step 4: Export .fbrd (board first - it's already in board view)-  adom-bridge fusion_export_source '{"outputPath": "/tmp/exports/MyDesign.fbrd"}'--  # Step 5: Switch to schematic (EDIT .s1 = first schematic sheet)-  adom-bridge fusion_electron_run '{"command": "EDIT .s1"}'--  # Step 6: Export .fsch-  adom-bridge fusion_export_source '{"outputPath": "/tmp/exports/MyDesign.fsch"}'--  # Step 7: Pull files to Docker-  adom-bridge pull_file '{"filePaths":["/tmp/exports/MyDesign.fbrd","/tmp/exports/MyDesign.fsch"], "saveTo":"/tmp/exports"}'-  ```--- **Critical gotchas:**-  - You MUST open the `.fprj` first - opening `.fbrd`/`.fsch` directly fails or triggers blocking dialogs-  - You MUST call `fusion_show_2d_board` before exporting `.fbrd` (the Electronics Design overview won't work)-  - Always export `.fbrd` FIRST (from board view), then switch to schematic for `.fsch`-  - If export fails with "file not found", the wrong workspace is active - screenshot to verify-  - After `fusion_open_cloud_file`, always screenshot to check for "Select Electronics Design File" dialog-  - `WRITE` command is blocked - it opens a blocking save dialog. Use `fusion_export_source` instead--- Note: `WRITE` is blocked - it opens a "Version Description" dialog on cloud docs even with a path argument (tested 2026-04-10). Use `fusion_save_to_cloud` to save to cloud, `fusion_export_source` for Fusion-format, or `fusion_export_eagle_source` for plain EAGLE format.--##### Plain EAGLE Source Export (`fusion_export_eagle_source`)-- `fusion_export_eagle_source` - Export the active electronics document as plain EAGLE XML `.sch` or `.brd`.-  - Args: `outputPath` (required - full path ending in `.sch` or `.brd`)-  - Internally: exports `.fsch`/`.fbrd` via `Document.CopyToDesktop`, then extracts the EAGLE XML from the ZIP container, cleans up the temp file.-  - The output is valid EAGLE XML (`<?xml><eagle version="9.7.0">...`) parseable by standalone EAGLE, KiCad import, or any XML tool.-  - Same workflow/prerequisites as `fusion_export_source` - just use `.sch`/`.brd` extensions instead of `.fsch`/`.fbrd`.--  ```bash-  # Board (.brd) - must be in PCB Editor / Board Layout-  adom-bridge fusion_show_2d_board-  adom-bridge fusion_export_eagle_source '{"outputPath": "/tmp/exports/MyDesign.brd"}'--  # Schematic (.sch) - must be in Schematic Editor-  adom-bridge fusion_electron_run '{"command": "EDIT .s1"}'-  adom-bridge fusion_export_eagle_source '{"outputPath": "/tmp/exports/MyDesign.sch"}'-  ```--##### Dialog Dismissal (`fusion_close_window`)-- `fusion_close_window` - Close a specific Fusion dialog by sending WM_CLOSE (equivalent to clicking X).-  - Args: `hwnd` (required - from `fusion_window_info` or `fusion_dismiss_blocking_dialogs` remaining[])-  - Works on dialogs that Escape doesn't close - e.g. "Recovered Documents"-  - Does NOT force-kill - the dialog can still intercept WM_CLOSE--##### Electronics Import (Round-Trip)-- `fusion_import_electronics` - Import Fusion-native `.fsch`, `.fbrd`, or `.flbr` files as new local documents-  - Uses `Document.newDesignFromLocal` under the hood-  - Auto-screenshots after import (catches blocking dialogs)-  - Args: `filePath` (required path on the Mac to .fsch, .fbrd, or .flbr)-  - After import, use `fusion_save_to_cloud` to persist to Fusion cloud-  - **`.fsch` import works standalone** - creates a new schematic project-  - **`.fbrd` import may fail** - boards have external references to schematics/libraries. Error: "New design cannot be created from a local file containing external references"-  - **`.flbr` import works standalone** - creates a new library project-  - For legacy EAGLE files: use `fusion_open_schematic` (.sch), `fusion_open_board` (.brd), `fusion_open_lbr` (.lbr)--##### Library Round-Trip Workflow-Export and re-import Fusion electronics libraries:-```bash-# 1. Open library from cloud-adom-bridge fusion_open_cloud_file '{"projectName":"Main","fileName":"Adom Common Components","folderPath":"Molecules/Libraries"}'--# 2. Export as .flbr (Fusion-native binary) and .scr (EAGLE script text)-adom-bridge fusion_save_lbr '{"outputPath":"/tmp/library.flbr"}'-adom-bridge fusion_export_lbr '{"outputPath":"/tmp/library.scr"}'-adom-bridge fusion_close_document--# 3. Re-import the .flbr-adom-bridge fusion_import_electronics '{"filePath":"/tmp/library.flbr"}'--# 4. Verify symbols survived round-trip-adom-bridge fusion_export_lbr '{"outputPath":"/tmp/library-verify.scr"}'--# 5. Save to cloud with new name-adom-bridge fusion_save_to_cloud '{"name":"Library-copy"}'-```--##### Demo Projects-171+ electronics molecules are exported in the `adom-bridge-demo` repo (separate from adom-bridge).-Three reference boards with full export formats:--| Board | Cloud Path | Layers | Components | Files |-|-------|-----------|--------|------------|-------|-| DRV8411A | Main / Molecules / XRP / DRV8411A | 4 | 29 | 27 |-| DRV8323SR | Main / Molecules / Experiments / MotorControl / DRV8323SR | 2 | 43 | 27 |-| VL53L8BreakoutMolecule | Main / Molecules / XRP / TimeOfFlightVL53L8 / VL53L8BreakoutMolecule | 2 | 30 | 27 |--Each folder contains: .fsch, .fbrd, bom.csv, cpl.csv, gerbers.zip, 6 board images, 7 3D renders (home/front/back/top/bottom/left/right), STEP, IGES, SAT, STL, 3MF, F3D, USDZ, board screenshot, 3D board screenshot.--#### Cloud Document Management--Manage Fusion 360 cloud documents (hub projects, files, versions). Required for 3D package workflows since EAGLE library 3D models are stored as cloud documents.--- `fusion_save_to_cloud` -- Save the active Fusion document to the cloud. Args: `name` (required), `projectName` (optional, defaults to active project), `folderPath` (optional), `description` (optional). Returns: `fileId`, `versionNumber`, `wipUrn` (if cloud-hosted).-- `fusion_list_cloud_projects` -- List all cloud projects in the user's hub. Returns array of `{name, id}` per hub.-- `fusion_list_cloud_files` -- List files in a cloud project/folder. Args: `projectName` (optional), `folderPath` (optional). Returns: `files` array with `{name, id, versionNumber, fileExtension, dateModified}` and `subfolders` array.-- `fusion_create_cloud_folder` -- Create a folder in a cloud project. Args: `folderName` (required), `projectName` (optional), `parentPath` (optional). Returns `folderId`. Idempotent - returns existing folder if it already exists.-- `fusion_check_recovery` -- Check if a cloud file has a recovery document from a previous crash. Args: `fileName` (required), `projectName` (optional), `folderPath` (optional). Returns `hasRecovery: true/false`. Use this BEFORE opening files to avoid the blocking "Open recovery document instead?" dialog. If recovery exists, call `fusion_open_cloud_file` with `recovery: "open"` (restore unsaved work) or `recovery: "discard"` (delete recovery, open cloud version).-- `fusion_open_cloud_file` -- Open a cloud file in Fusion by name. **If a recovery document exists and no `recovery` arg is given, the command STOPS and reports the recovery instead of opening** - you must decide whether to preserve or discard unsaved work. Args: `fileName` (required), `projectName` (optional), `folderPath` (optional), `recovery` ("open" = restore unsaved work, "discard" = delete recovery and open cloud version).-- `fusion_export_cloud_file` -- Export the active Fusion document to a local file for transfer back to Docker. Args: `outputPath` (required), `format` (optional, default "step"). The exported file can then be pulled back to Docker via `pull_file`.-- `fusion_delete_cloud_file` -- Delete a cloud file by name. Args: `fileName` (required), `projectName` (optional), `folderPath` (optional). File must not be open in Fusion - close it first with `fusion_close_document`.-- `fusion_walk_cloud_tree` -- **Long-running.** BFS walk of a cloud folder tree. Returns a flat list of all files and folders. Runs entirely on the Fusion main thread - **blocks all other add-in commands** until done (check progress with `fusion_addin_status`).-  - Args: `projectName` (optional), `folderPath` (optional, starting folder), `maxDepth` (default 10), `maxFolders` (default 500), `extensions` (optional list, e.g. `["f3d","fprj"]`), `nameContains` (optional substring filter), `includeFiles` (default true)-  - Returns: `{project, rootFolder, folders[], files[], stats: {foldersVisited, foldersSkipped, filesFound, maxDepthReached, truncated}}`-  - **Per-folder timeout (30s):** If a single folder's cloud API calls take >30s (common for large projects), the folder is skipped and counted in `foldersSkipped`. This prevents indefinite hangs.-  - **Progress tracking:** While running, `fusion_addin_status` returns `walkProgress` with `{foldersVisited, filesFound, currentFolder, queueSize}` - poll this every 1–10s to monitor progress (see "Live folder progress streaming" below).-  - **Non-blocking alternative:** Use `fusion_search_cloud_files` for targeted searches, or `fusion_list_cloud_files` for single-folder listings (these are faster but don't recurse).-  - Example: `adom-bridge fusion_walk_cloud_tree '{"projectName":"Main","folderPath":"Molecules","nameContains":"DRV","extensions":["fprj"]}'`--#### Live folder progress streaming with `watch`--For long walks, use the built-in `watch` wrapper. It spawns the inner search command on a worker thread, polls `fusion_addin_status` internally, and emits one JSON event per line to stdout as the walker visits each folder. **No manual polling loop needed.**--```bash-adom-bridge watch '{"command":"fusion_walk_cloud_tree","args":{"projectName":"Main","folderPath":"Molecules","nameContains":"BQ25792"}}'-```--Output is one JSON object per line, three event types:--```jsonl-{"event":"started","command":"fusion_walk_cloud_tree","args":{...},"interval":2,"_hint":"streaming progress events follow, one per line, ending with 'complete' or 'error'"}-{"event":"progress","busyCommand":"walk_cloud_tree","elapsedSeconds":15.0,"foldersVisited":14,"queueSize":50,"filesFound":0,"currentFolder":"Molecules/Sensing"}-{"event":"progress","busyCommand":"walk_cloud_tree","elapsedSeconds":23.4,"foldersVisited":22,"queueSize":108,"filesFound":0,"currentFolder":"Molecules/Examples"}-{"event":"progress","busyCommand":"walk_cloud_tree","elapsedSeconds":31.8,"foldersVisited":30,"queueSize":100,"filesFound":0,"currentFolder":"Molecules/RAPID NAME TAGS/Connor Wood"}-... (one per real change in walkProgress, deduped) ...-{"event":"complete","result":{"folders":[...],"files":[...],"stats":{"foldersVisited":169,"filesFound":12,"truncated":false}}}-```--Read stdout line-by-line. Stop when you see `event:complete` or `event:error`. The full final result is in the `complete` event's `result` field.--**Optional `interval` arg** (default 2s, clamped to [1, 30]):--```bash-adom-bridge watch '{"command":"fusion_walk_cloud_tree","args":{...},"interval":1}'-```--**For Claude Code consumers**: pipe `watch` directly into the `Monitor` tool. Each JSON line becomes a real-time event notification in the chat - you (and the user) see folder names appear one-by-one as the walker visits them. No bash loop, no `disown`, no subprocess gymnastics. Verified live in 1.3.16 on a 169-folder walk that returned all 12 BQ25792 cloud files cleanly.--**Watchable commands** (whitelist): `fusion_walk_cloud_tree`, `fusion_search_cloud_files`. Other commands return `success:false` with a `_hint` listing the watchable set.--**When NOT to use watch**: short single-folder operations (`fusion_list_cloud_files`, `fusion_open_cloud_file`) - those return in <2s and don't need streaming. The `watch` wrapper is purely for the long BFS commands.-- `fusion_search_cloud_files` -- **Long-running.** Recursive substring search on file names across cloud folders. v1.0.2+ of the add-in adds: per-folder timeout, doEvents() every 50 files, per-file try/except, iterative BFS, and a stale-lock watchdog - Fusion stays responsive throughout (no "Not Responding" freeze).-  - **Args (no hard upper caps in v1.0.2+):** `query` (required, substring, case-insensitive), `projectName` (optional, defaults to active), `folderPath` (optional starting subfolder - **narrow with this**), `recursive` (default false), `maxDepth` (default 2), `maxFolders` (default 10), `maxResults` (default 20), `folderTimeout` (default 30s), `searchTimeout` (default 120s), `timeout` (HTTP envelope, default 620s).-  - **Before calling:** if the user knows roughly where the file is (e.g. customer-named folder), **ask them**. Naming a subfolder cuts 5-40 min searches down to ~10s.-  - **Why slow:** Autodesk's free Fusion 360 Python API has no indexed file-search endpoint. We walk the Data API one folder at a time - each = one HTTP round-trip to Autodesk. **This is an Autodesk API limitation, not adom-bridge's.** When telling the user the search is taking a while, attribute it to Autodesk / Fusion 360, not to adom-bridge's bridge. **There is now a FAST native alternative - `aps_search` (see "APS - fast indexed cloud search" below).** It hits Autodesk Platform Services' indexed Data Management API and returns ~instantly, even when Fusion is CLOSED. Call `aps_status` first; if `configured:true`, prefer `aps_search` and only fall back to this folder-walking verb when APS isn't set up.-  - **Interpreting results (critical for no-false-negatives):** the response contains `searchComplete` (bool), `foldersSkipped`, `filesSkipped`, `truncated`, `folderLimitReached`, `searchTimedOut`. `searchComplete:true` ONLY when **all five** are clean - that's the confidence flag. If `searchComplete:false`, the search hit a cap before exhausting the scope; **don't report "file not found"** - re-run with broader caps OR narrower `folderPath`.-  - **Case sensitivity:** fully case-insensitive both directions (query and file names lowercased). Substring match, not whole-word - `"cosm"` matches `COSMIIC`, `COSMOCOIL`, etc.-  - **Cost feedback in response:** `costAnalysis: {elapsedSeconds, foldersPerSecond, estimatedSecondsPer100Folders}` so the AI can budget the next search realistically.-  - **Real numbers from a live test:** searching `Main/Molecules` recursively (173 folders deep, max 8 depth) for "cosmiic" returned in 168 s with `searchComplete:true, totalFound:3`. Fusion stayed `main_thread:responsive` throughout.-  - **Pair with `watch`** for streaming progress updates: see below.--#### APS - fast indexed cloud search (v1.8.182+)--`aps_search` is a **native, ~instant** alternative to the folder-walking `fusion_search_cloud_files`. It queries **Autodesk Platform Services** (APS, formerly Forge) **Data Management API**, which has a real server-side index - so a search that takes minutes by folder-walking returns in well under a second, and it works **even when Fusion 360 is closed** (it's pure HTTPS, no bridge required). adom-bridge runs its own 3-legged **PKCE** OAuth, so the user's APS **client secret never leaves their machine**.--**One-time setup (user side):**-1. Register a free app at <https://aps.autodesk.com> → enable the **Data Management API**.-2. Set the app's **Callback URL** to exactly `http://localhost:8910/aps/callback`.-3. Put the **Client ID** in Bridge config key `aps_client_id` (in `~/.adom/config.json`) or via Settings.-4. Run `aps_auth` once - it opens the system browser for Autodesk sign-in. Tokens cache in `~/.adom/aps_tokens.json` and auto-refresh; you won't be prompted again.--**Verbs:**-- `aps_status` - **call this first.** Non-prompting. Returns `{configured, signedIn}`. `configured:false` → no client id; use `fusion_search_cloud_files`. `configured:true, signedIn:false` → run `aps_auth`. Both true → `aps_search` is ready.-- `aps_auth` - interactive sign-in (opens browser). One-time per device.-- `aps_hubs` - `{hubs[]{id,name}}` (your Autodesk teams).-- `aps_projects {hubId?}` - `{hubId, projects[]{id,name}}` (default: first hub).-- `aps_search {query, projectName?, projectId?, hubId?}` - `{query, hubId, count, results[]{name,id,type,lastModified,project}}`. `query` is a case-insensitive substring of the file's displayName. Without `projectName`/`projectId` it searches up to 8 projects in the hub. Open a hit with `fusion_open_cloud_file {fileName, projectName}`.--**Decision flow for an AI doing a cloud file search:** `aps_status` → if `configured` (sign in with `aps_auth` if needed) use `aps_search`; else fall back to `fusion_search_cloud_files` and tell the user that registering a free APS app (above) would make future searches instant.--**Export formats for `fusion_export_cloud_file`:**--| Format | Extension | Use case |-|--------|-----------|----------|-| `step` | .step | Industry-standard CAD interchange (default) |-| `stl` | .stl | 3D printing, mesh-based |-| `f3d` | .f3d | Fusion 360 native archive (preserves all features) |-| `iges` | .iges | Legacy CAD interchange |-| `sat` | .sat | ACIS solid modeling kernel format |-| `smt` | .smt | Parasolid format |--Also supported for import via `fusion_import_step`: STEP (.step/.stp), STL (.stl), IGES (.iges/.igs), SAT (.sat), SMT (.smt), OBJ (.obj), F3D (.f3d).--**Round-trip: workspace → Fusion Cloud → workspace**--```bash-# === workspace to Fusion Cloud ===-# 1. Send file from Docker to the Mac-adom-bridge send_files '{"files": [{"path": "/home/user/component.step"}]}'-# 2. Import into Fusion-adom-bridge fusion_import_step '{"filePath": "/Users/<you>/Downloads/component.step"}'-# 3. Save to cloud (gets a wip_urn for 3D library linking)-adom-bridge fusion_save_to_cloud '{"name": "my-component", "projectName": "Personal"}'--# === Fusion Cloud to Docker ===-# 1. Find and open the cloud file-adom-bridge fusion_walk_cloud_tree '{"projectName": "Personal", "nameContains": "my-component"}'-adom-bridge fusion_open_cloud_file '{"fileName": "my-component", "projectName": "Personal"}'-# 2. Export to local filesystem-adom-bridge fusion_export_cloud_file '{"outputPath": "/tmp/export/my-component.step", "format": "step"}'-# 3. Pull back to Docker-adom-bridge pull_file '{"path": "/tmp/export/my-component.step"}'--# === Cloud management ===-adom-bridge fusion_list_cloud_projects '{}'-adom-bridge fusion_create_cloud_folder '{"folderName": "Electronics", "projectName": "Main"}'-adom-bridge fusion_list_cloud_files '{"projectName": "Main", "folderPath": "Electronics"}'-adom-bridge fusion_delete_cloud_file '{"fileName": "old-file", "projectName": "Main"}'-```--#### Manufacturing Exports (Gerbers, BOM, CPL)--Export manufacturing files from an open PCB board - everything needed to fabricate boards and assemble components via Adom's PCBA service. **All manufacturing commands require a .brd board open in PCB Editor** (use `fusion_open_board` or `fusion_show_2d_board`).--**Recommended workflow order:** `detect_layers` → `set_design_rules` → DRC → `export_gerbers` → `export_bom` → `export_cpl` → `pull_file` all back to Docker.--Every manufacturing command returns structured JSON with:-- `message` - AI-oriented summary explaining what was produced and why it matters-- `nextSteps[]` - ordered list of what to run next in the manufacturing pipeline-- `hint` - tips for interpreting results or recovering from issues-- `data` - structured metadata (paths, counts, layer info) for programmatic use--**Decision guide - which command to run:**-- **Don't know the layer count?** → Run `fusion_detect_layers` first-- **Need to check if the board meets fab specs?** → Run `fusion_set_design_rules` then DRC-- **Ready to generate fab files?** → Run `fusion_export_gerbers`, then `fusion_export_bom`, then `fusion_export_cpl`-- **Need visual review before export?** → Run `fusion_export_board_image` with preset `assembly_top` or `fabrication`-- **Something failed?** → Check `data.hint` and `data.recoverySteps` in the error response--**Commands:**--- `fusion_detect_layers` -- Detect if the open board is 2-layer or 4-layer. Uses ULP script (primary) and CAM comparison (fallback). Returns `layerCount`, `copperLayers[]`, `method` (how it was detected), and `nextSteps[]`. **Run this first** - all other manufacturing commands auto-detect layers too, but running this explicitly gives you the data before committing to exports.--- `fusion_set_design_rules` -- Apply Adom's JLCPCB-derived design rules (.edru XML files) to the open board. Auto-detects 2-layer vs 4-layer and loads the appropriate rule set. Returns `description` (human-readable rule summary), `edruFile`, and `nextSteps[]`.-  - `action`: `"apply"` (default) loads rules into the board; `"export"` saves current board rules to a file; `"show"` displays rule capabilities without modifying anything-  - `layers`: `"auto"` (default), `"2"`, or `"4"` - force a specific rule set-  - After applying: run `fusion_electron_run '{"command": "DRC"}'` to check for violations. DRC markers appear in the board editor.--- `fusion_apply_instapcb_rules` -- Convenience wrapper that applies the bundled Adom InstaPCB design rule sets without needing a local `.edru` file. Args: `layers` (`"2"` or `"4"`). Sends the bundled `.edru` from Docker to the Mac automatically and loads it via the EAGLE `drc load` command. Use this instead of `fusion_set_design_rules` when you just want Adom's standard 2-layer or 4-layer InstaPCB rules.--- `fusion_load_design_rules` -- Generic loader for ANY custom `.edru` file by path. Args: `filePath`. Use this for third-party fab vendor rules (JLCPCB, PCBWay, OSHPark, etc.) that the user has on disk.--- `fusion_export_gerbers` -- Export Gerber (RS-274X) + Excellon drill files as a ZIP. Auto-detects 2-layer vs 4-layer and selects the correct JLCPCB-compatible CAM job. Returns `zipPath`, `zipSizeKB`, `files[]` (list of gerber files in the ZIP with sizes), `layerCount`, and `nextSteps[]`.-  - `outputDir`: directory for the output ZIP (default: `/tmp/adom-gerbers/`)-  - `boardName`: prefix for the ZIP filename (default: from active document name)-  - `layers`: `"auto"` (default), `"2"`, or `"4"` - force CAM job selection-  - Output ZIP contains: GTL, GBL (copper), GTS, GBS (solder mask), GTP, GBP (paste), GTO, GBO (silkscreen), GKO (outline), XLN (drill). 4-layer boards also get G1, G2 (inner copper).--- `fusion_export_bom` -- Export Bill of Materials as CSV. Groups identical parts by value+package with quantity counts. Returns `componentCount`, `uniquePartCount`, and `nextSteps[]`.-  - `outputPath`: (default: `/tmp/adom-bom.csv`)-  - `grouped`: `true` (default) groups by value+package; `false` lists every component individually-  - Output columns: Comment, Designator, Footprint, Quantity, Library - compatible with JLCPCB, PCBWay, Mouser, Digi-Key.--- `fusion_export_cpl` -- Export Component Placement List (pick-and-place) as CSV. Returns `totalPlacements`, `topCount`, `bottomCount`, and `nextSteps[]`.-  - `outputPath`: (default: `/tmp/adom-cpl.csv`)-  - `side`: `"all"` (default), `"top"`, or `"bottom"` - filter for single-sided assembly-  - Output columns: Designator, Mid X, Mid Y, Layer, Rotation - coordinates in mm.--- `fusion_export_board_image` -- Export PNG image of the board with layer presets. Returns `fileSize`, `preset`, and `nextSteps[]`.-  - `outputPath`: (default: `/tmp/adom-board.png`)-  - `dpi`: resolution (default: 300, max: 600)-  - `preset`: layer preset name (see table below)-  - `layers`: custom layer numbers as int array - overrides preset-  - `monochrome`: `true` for black & white-  - `listPresets`: set `true` to get available presets instead of exporting--**Layer presets for `fusion_export_board_image`:**--| Preset | Layers | Description |-|--------|--------|-------------|-| `all` | All | Every layer visible |-| `top_copper` | 1, 17, 18 | Top copper + pads + vias |-| `bottom_copper` | 16, 17, 18 | Bottom copper + pads + vias |-| `top_silkscreen` | 21, 25 | Top silkscreen + component names |-| `bottom_silkscreen` | 22, 26 | Bottom silkscreen + component names |-| `top_soldermask` | 29 | Top solder mask openings |-| `bottom_soldermask` | 30 | Bottom solder mask openings |-| `top_paste` | 31 | Top paste/stencil openings |-| `bottom_paste` | 32 | Bottom paste/stencil openings |-| `board_outline` | 20 | Board outline (dimension layer) |-| `drill` | 44, 45, 17, 18 | Drill holes + vias |-| `assembly_top` | 1, 17, 18, 20, 21, 25, 51 | Top assembly - copper + silk + outline |-| `assembly_bottom` | 16, 17, 18, 20, 22, 26, 52 | Bottom assembly - copper + silk + outline |-| `fabrication` | 1, 16, 17–20, 21, 22, 25, 26, 29, 30, 51 | Full fabrication view |--**Adom InstapcbPCB manufacturing capabilities (used by `fusion_set_design_rules`):**--| Parameter | Metric | Imperial |-|-----------|--------|----------|-| Layers | 1, 2, 4, 6 | - |-| Min trace width | 0.08mm | 3 mil |-| Min trace spacing | 0.08mm | 3 mil |-| Min via drill | 0.2mm | 8 mil |-| Min silkscreen text | 0.1mm | 4 mil |-| Board edge clearance | 0.05mm | 2 mil |-| Board thickness | 1.6mm | 63 mil |-| Copper weight | 0.5 oz (17.5 μm) | - |-| Solder mask | Green | - |-| Surface finish | HASL / ENIG | - |-| Turnaround | 4 hours (fab + assembly) | - |--**Manufacturing workflow - Fusion to Adom PCBA:**--```bash-# 1. Open the board-adom-bridge fusion_open_board '{"filePath": "C:/projects/myboard.brd"}'--# 2. Detect layer count (auto-selects 2-layer or 4-layer rules/CAM)-adom-bridge fusion_detect_layers--# 3. Apply Adom design rules for the detected layer count + run DRC-adom-bridge fusion_set_design_rules '{"action": "apply"}'-adom-bridge fusion_electron_run '{"command": "DRC"}'--# 4. Export manufacturing files (gerbers auto-select correct CAM job)-adom-bridge fusion_export_gerbers '{"outputDir": "/tmp/mfg"}'-adom-bridge fusion_export_bom '{"outputPath": "/tmp/mfg/bom.csv"}'-adom-bridge fusion_export_cpl '{"outputPath": "/tmp/mfg/cpl.csv"}'--# 5. Export board images for review-adom-bridge fusion_export_board_image '{"outputPath": "/tmp/mfg/top-copper.png", "preset": "top_copper"}'-adom-bridge fusion_export_board_image '{"outputPath": "/tmp/mfg/assembly-top.png", "preset": "assembly_top"}'-adom-bridge fusion_export_board_image '{"outputPath": "/tmp/mfg/board-outline.png", "preset": "board_outline"}'--# 6. Pull files back to Docker for Adom PCBA ordering-adom-bridge pull_file '{"path": "/tmp/mfg/bom.csv"}'-adom-bridge pull_file '{"path": "/tmp/mfg/cpl.csv"}'-```  ### Desktop Tools @@ -2003,17 +1410,6 @@ curl -sf http://127.0.0.1:8766/health  `shell_execute` runs via `sh -c` on the Mac. For multi-line work prefer `run_script` (base64, no quoting hell). Use `python3`, not `python`. -## Building from Source--```bash-cd cli && cargo build --release-# Binary at: cli/target/release/adom-bridge-```--## Repo--[github.com/adom-inc/adom-bridge](https://github.com/adom-inc/adom-bridge)- ## Run wiki ops on the user's Mac - `wiki_exec` (v1.9.116+)  Bridge bundles the `adom-wiki` CLI inside the app (Contents/Resources), and `wiki_exec` runs it ON THE MAC - so version-controlling a local project (KiCad board, docs folder) on wiki.adom.inc needs NO per-file `pull_file` round trip to the container and there is no container/Mac drift.