Embody AGENTS.md

Embody + Envoy - AI Instructions

This project uses Embody (TouchDesigner externalization) and Envoy (MCP server for AI coding tools).

• Embody externalizes TouchDesigner operators to version-controlled files (.py, .tox, .tdxn, .json, etc.)
• Envoy provides MCP tools for AI assistants to inspect and modify the live TD network
• Use the Configure For toggles on the Embody COMP's Envoy page to regenerate these files for your AI tool (more than one client can be on at once)

Note: For Claude Code users, a CLAUDE.md with modular .claude/rules/ and .claude/skills/ is also generated. This AGENTS.md is the universal fallback read by Codex, Cursor, GitHub Copilot, Windsurf, Gemini, and others.

Critical Rules

1. Prefer the externalized network file for reading TDXN-externalized COMPs - these are YAML on disk with complete network structure (operators, parameters, connections, positions, flags, DAT content, annotations). Reading them directly is faster than MCP round-trips. Never glob for an extension: Embody writes .tdxn, and keeps writing .tdn for any COMP externalized before Embody 6.1 - both are read and round-tripped forever, so a project can hold a mix. Let externalizations.tsv or get_externalizations name the exact file instead. The strategy column value is tdn for all of them, unchanged by the rename - searching for a tdxn strategy finds nothing and will make you wrongly conclude the project has no externalized networks. To edit: modify the file on disk, then call import_network via MCP with the COMP path, the parsed network, and clear_first=True to reload it in TD. Use MCP when you need live runtime state (evaluated expressions, cook errors) or for non-TDXN operators.
2. Use Envoy MCP tools for live TD state and non-TDXN operators - never say "I can't access that binary file." For operators not externalized as TDXN, use MCP tools to inspect and modify them.
3. Do NOT assume network paths - use query_network on / to discover the actual root structure.
4. Default new COMPs to Embody's container - execute_python with result = op.Embody.parent().path returns the same home every run. Build in ui.panes.current.owner.path only when you have deliberately navigated into a content network, and never treat the bare root / as that home.
5. Never edit externalizations.tsv directly - managed exclusively by Embody's tracking system.
6. Always use forward slashes in file paths.
7. Check for errors and warnings after each group of operator creations -- get_op_errors with recurse=true once the group is wired/positioned.
8. Batch repetitive MCP operations -- never make 3+ individual calls to the same tool. Use batch_operations for repeated positioning, connecting, parameter, or flag edits; use execute_python for computed or looped logic.
9. Thread boundary: MCP server worker thread must never import TD modules. All TD access goes through _execute_in_td().