---
name: externalize-operator
description: "MUST READ before calling externalize_op or save_externalization. Required workflow steps."
---
<!-- Generated by Embody/Envoy - Do not remove this comment -->

# Externalize Operator Workflow

## Tagging (includes save)

`externalize_op` tags the operator AND writes it to disk in one step (it calls `Update()` internally). No separate save is needed.

1. **Tag and externalize**: `externalize_op` on the operator (auto-detects type if omitted)
2. **Verify**: `get_externalization_status` to confirm dirty state and file path
3. **Inspect**: Verify file exists in `embody/` via file inspection

## Re-exporting After Changes

`save_externalization` force re-exports an already-externalized operator. Use it after modifying an operator in TD when you need to update its file on disk.

## Creating Python Files for TouchDesigner

When creating Python files (scripts, extensions, test files, callbacks):
1. Create the textDAT in TouchDesigner first (via MCP `create_op` or in TD UI)
2. Write the Python code into the DAT (via MCP `set_dat_content`)
3. Tag the DAT for externalization (`externalize_op`) — Embody writes the `.py` file to disk

**NEVER** manually set the `file` and `syncfile` parameters — Embody handles all file path management.

## Exporting a Portable Tox

Export any COMP as a self-contained `.tox` with all Embody metadata stripped:

- **Via MCP**: `execute_python` with `op.Embody.ExportPortableTox(target=op('/path/to/comp'), save_path='/output/path.tox')`
- **Via UI**: Manager UI > Actions popup > "Export portable tox"

The exported `.tox` works in any TD project with no missing file errors.

## Checking Status

- `get_externalizations` — list all externalized operators with status
- `get_externalization_status` — get dirty state, build number, timestamp, file path for a specific operator

## TDN Export — Palette COMP Handling

When exporting a TDN-strategy COMP whose network contains TD palette components (e.g. `abletonLink`, Widget components, anything under `Samples/Palette/`), Embody consults the `Tdnpalettehandling` par on the Embody COMP's TDN page:

- **Ask** (default): On first encounter of each palette COMP, a four-button dialog appears — *Black Box* (this COMP), *Full Export* (this COMP), *Black Box for All*, *Full Export for All*. The per-COMP choice is stored via `comp.store('_tdn_palette_handling', ...)` so repeated exports don't re-prompt.
- **Black Box**: reference the palette only, emit `"palette_clone": true`, skip internal children. Correct for stock palette COMPs.
- **Full Export**: export all children as if the COMP were a regular user COMP. Use only when palette internals have been heavily customized.

Check and override programmatically: `op.Embody.par.Tdnpalettehandling = 'blackbox' | 'fullexport' | 'ask'`, or force a specific COMP: `op('/path/to/comp').store('_tdn_palette_handling', 'fullexport')`.
