---
name: adom-molecule
description: >
  Use when the user wants to create a molecule, import KiCad/Fusion 360/EasyEDA files
  into the Adom molecule system, upload a molecule, optimize a molecule's 3D model,
  list molecules, or delete a molecule. Trigger words: create molecule, import molecule,
  upload molecule, molecule from kicad, molecule from fusion, import kicad files,
  upload fusion files, list molecules, delete molecule, optimize molecule, usdz to glb,
  kicad to molecule, fusion to molecule.
---

# Adom Molecule CLI

Create and manage Adom molecules from KiCad, Fusion 360, and EasyEDA design files.
Wraps the Hydrogen molecule import pipeline — file upload, Blender 3D optimization,
listing, and deletion.

## Quick Start

```bash
# Check connectivity
adom-molecule health

# Create a KiCad molecule (uploads files + auto-queues 3D optimization)
adom-molecule create --source kicad --name "MyBoard" --owner john \
    --glb model.glb --pcb board.kicad_pcb --sch schematic.kicad_sch

# Create a Fusion 360 molecule
adom-molecule create --source fusion --name "MyEnclosure" --owner john \
    --usdz model.usdz --f3d design.f3d --brd board.brd --silk-top silkscreen.png

# List all molecules
adom-molecule list

# Delete a molecule
adom-molecule delete --owner john --name "MyBoard"
```

## Commands

### `adom-molecule health`

Check connectivity to the Hydrogen and Carbon APIs.

**Example:**
```bash
adom-molecule health
# OK: Hydrogen API reachable (https://hydrogen.adom.inc)
# OK: Carbon API reachable (https://carbon.adom.inc)
```

---

### `adom-molecule create`

Upload design files and create a molecule. Auto-queues 3D optimization unless `--no-optimize` is passed.

| Flag | Required | Description |
|------|----------|-------------|
| `--source` | no | `kicad`, `fusion`, or `easyeda`. Auto-detected from files if omitted. |
| `--name` | yes | Molecule name |
| `--owner` | yes | Owner username or org name |
| `--glb` | KiCad | Path to `.glb` 3D model |
| `--pcb` | KiCad | Path to `.kicad_pcb` board file |
| `--sch` | KiCad | Path to `.kicad_sch` schematic file |
| `--pro` | no | Path to `.kicad_pro` project file |
| `--usdz` | Fusion | Path to `.usdz` 3D model |
| `--f3d` | no | Path to `.f3d` Fusion native file |
| `--brd` | no | Path to `.brd` board file |
| `--sch-eagle` | no | Path to `.sch` EAGLE schematic file |
| `--silk-top` | Fusion | Path to silkscreen top `.png` |
| `--silk-bottom` | no | Path to silkscreen bottom `.png` |
| `--obj` | EasyEDA | Path to `.obj` 3D model |
| `--extra` | no | Additional files (repeatable) |
| `--no-optimize` | no | Skip automatic optimization queue |

**KiCad example:**
```bash
adom-molecule create --name "RP2040_Core" --owner adom \
    --glb /home/adom/project/molecules/rp2040/model.glb \
    --pcb /home/adom/project/molecules/rp2040/board.kicad_pcb \
    --sch /home/adom/project/molecules/rp2040/schematic.kicad_sch \
    --pro /home/adom/project/molecules/rp2040/project.kicad_pro
# OK: Created molecule "RP2040_Core" (v1). Optimization queued.
```

**Fusion 360 example:**
```bash
adom-molecule create --source fusion --name "Enclosure_v2" --owner john \
    --usdz /home/adom/exports/enclosure.usdz \
    --f3d /home/adom/exports/enclosure.f3d \
    --brd /home/adom/exports/board.brd \
    --silk-top /home/adom/exports/silkscreen_top.png
# OK: Created molecule "Enclosure_v2" (v1). Fusion optimization queued.
```

**EasyEDA example:**
```bash
adom-molecule create --source easyeda --name "Sensor_Board" --owner adom \
    --obj /home/adom/exports/sensor.obj
# OK: Created molecule "Sensor_Board" (v1).
```

**With extra files:**
```bash
adom-molecule create --name "MyBoard" --owner adom \
    --glb model.glb --pcb board.kicad_pcb --sch schematic.kicad_sch \
    --extra datasheet.pdf --extra bom.csv
# OK: Created molecule "MyBoard" (v1). Optimization queued. 2 extra file(s) attached.
```

---

### `adom-molecule optimize`

Manually queue a KiCad molecule for 3D optimization (Blender pipeline).
Normally not needed — `create` does this automatically.

| Flag | Required | Description |
|------|----------|-------------|
| `--owner` | yes | Owner username or org |
| `--name` | yes | Molecule name |
| `--version` | yes | Version string (e.g. `v1`) |
| `--glb` | yes | GLB filename that was uploaded |

**Example:**
```bash
adom-molecule optimize --owner adom --name "RP2040_Core" --version v1 --glb model.glb
# OK: Optimization queued for "RP2040_Core" v1 (job abc123)
```

---

### `adom-molecule optimize-fusion`

Manually queue a Fusion 360 molecule for USDZ-to-GLB optimization.

| Flag | Required | Description |
|------|----------|-------------|
| `--owner` | yes | Owner username or org |
| `--name` | yes | Molecule name |
| `--version` | yes | Version string |
| `--usdz` | no | USDZ filename |
| `--f3d` | no | F3D filename |
| `--brd` | no | BRD filename |
| `--silk-top` | yes | Silkscreen top filename |

**Example:**
```bash
adom-molecule optimize-fusion --owner john --name "Enclosure_v2" --version v1 \
    --usdz enclosure.usdz --silk-top silkscreen_top.png
# OK: Fusion optimization queued for "Enclosure_v2" v1 (job def456)
```

---

### `adom-molecule list`

List all molecules in the system.

**Example:**
```bash
adom-molecule list
# OK: 0 molecule(s)
# (empty — no molecules created yet)
```

---

### `adom-molecule delete`

Delete a molecule.

| Flag | Required | Description |
|------|----------|-------------|
| `--owner` | yes | Owner username or org |
| `--name` | yes | Molecule name |

**Example:**
```bash
adom-molecule delete --owner john --name "OldBoard"
# OK: Deleted molecule "OldBoard" owned by john
```

---

### `adom-molecule install`

Deploy the SKILL.md to `~/.claude/skills/adom-molecule/` and optionally copy
the binary to `/usr/local/bin/`.

**Example:**
```bash
adom-molecule install
# OK: Installed skill to /home/adom/.claude/skills/adom-molecule/SKILL.md
# OK: Binary already at /usr/local/bin/adom-molecule
```

## Source Types & Required Files

| Source | Required Files | Optional Files |
|--------|---------------|----------------|
| **KiCad** | `.glb`, `.kicad_pcb`, `.kicad_sch` | `.kicad_pro` |
| **Fusion 360** | `.usdz`, silkscreen top `.png` | `.f3d`, `.brd`, `.sch`, silkscreen bottom `.png` |
| **EasyEDA** | `.obj` | — |

If `--source` is omitted, it's auto-detected from file extensions:
- `.glb`, `.kicad_pcb`, `.kicad_sch` → KiCad
- `.usdz`, `.f3d`, `.brd`, `.png` → Fusion 360
- `.obj` → EasyEDA

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `ADOM_HYDROGEN_URL` | `https://hydrogen.adom.inc` | Hydrogen API base URL |
| `ADOM_CARBON_URL` | `https://carbon.adom.inc` | Carbon API base URL |

## Troubleshooting

### `ERROR: Failed to create molecule: Access Key Id does not exist`
The Hydrogen server's S3 storage credentials are expired or misconfigured.
This is a server-side issue — contact the Adom team.

### `ERROR: Cannot reach Hydrogen API`
Check your network connection. The API is at `https://hydrogen.adom.inc`.
From inside an Adom container, this should always be reachable.

### Optimization queued but molecule doesn't update
The Blender optimization pipeline runs asynchronously. Check the molecule
page at `https://hydrogen.adom.inc/{owner}/molecules/{name}` after a few minutes.