wtd-libreflow-addon/CLAUDE.md

Melvile Tools: notes for Claude

Blender add-on (Blender 5.2) for the Melvile pipeline at Walking The Dog: Sanity Check, Rename, Shot Viewer and Scene Manager panels in the 3D View sidebar (WTD tab). README.md is the user guide: keep it up to date with every user-visible change.

Layout and conventions

• config.py: every production value (prefixes, formats, patterns, modes). Values are read at run time (config.X, never copied at import) because a studio JSON file can override them (add-on preferences "Config Override", or WTD_SANITY_CONFIG). New tunable values go here, with a comment, and in the README's Configuration table.
• ui/panel.py: all panels. Operators live with their tool (rename.py, shot_viewer.py, scene_manager/, ui/operators.py for the Sanity Check).
• checks/: sanity checks, auto-registered (see README > For developers).
• __init__.py deletes cached submodules on reload, so Reload Scripts picks up every file.
• Versions: blender_manifest.toml and bl_info in __init__.py (keep both in sync).
• Style: match the surrounding code; short docstrings, few comments, no heavy abstractions.

Working with the user

• Commits: when asked, create a branch from master, commit there (end with the Co-Authored-By line), and give the user the merge / push / branch-delete commands: they run them themselves. Only commit straight on master when told to.
• Real Blender API facts beat memory: probe in headless Blender before relying on an API.

Testing

Blender binary: macOS /Applications/Blender.app/Contents/MacOS/Blender, Windows blender.exe from the install folder. Import the add-on in tests by putting the folder that contains this repo on sys.path and importing the repo folder name (see dev/test_scene_manager.py).

• Headless: blender -b --factory-startup --python-exit-code 1 --python <script> -- <args>. Timers do not run in background mode: pump background jobs by hand (scene_manager.ipc._poll()).
• UI: run Blender with a window (--factory-startup <file.blend> --python <script>, a .blend argument avoids the splash), drive it with bpy.app.timers, take screenshots with bpy.ops.screen.screenshot_area, quit with bpy.ops.wm.quit_blender(). A sidebar tab (region.active_panel_category) can only be set once the region has been drawn.
• Scene Manager without Libreflow (dev/):
  1. blender -b --factory-startup --python dev/make_test_assets.py -- <workdir>
  2. python dev/fake_libreflow.py <workdir> (keep running; restart for a clean state)
  3. blender -b --factory-startup --python-exit-code 1 --python dev/test_scene_manager.py -- <workdir> (36 checks, "All checks passed"). The fake server follows the real wtdcmds replies; check them against the real Libreflow when one is available.

External pieces

• Libreflow wtdcmds extension (commands used by the Scene Manager), on the share: WG/_Dev/GIT/ndemaerschalk/_MELVILE/libreflow_dev_utils/dev/src/wtdcmds/ (src/libreflow/extensions/wtdcmds/wtd_cmds.py, BLENDER_ADDON_BRIEF.md). Server address/token: ~/.kabaret/ipc/server.json (config LIBREFLOW_SERVER_FILE).
• Add Camera Rigs extension: bpy.ops.object.build_camera_rig(mode=...) builds the Shot Viewer cameras. It finds its rigs by the rig_id custom property, not by name.
• tools_ops.py "Get Oid" uses the separate kabaret Blender client (bpy.ops.kabaret.cmds_call).

Design notes (found by testing)

• Shot Viewer: shots are timeline markers bound to cameras, in one scene. Setting scene.frame_current does not switch the camera (only frame_set does): set scene.camera explicitly.
• Scene Manager: tags live on bpy.types.Library only. Library overrides lose custom properties when they resync, so instances are traced back to their library (empty → instance_collection.library, override → override_library.reference.library).
• library.reload() invalidates every Python reference to linked and override data: look IDs up again afterwards.
• Background requests (scene_manager.ipc.run) hand results back through a timer; in callbacks, find scenes by name (bpy.context.scene is not reliable in timers).

Open points

• First run of the Scene Manager against a real Libreflow (only tested with the fake server): connection, casting, load, update, assetize, Windows paths.
• Asset type names assumed chars / props / sets (SCENE_MANAGER_LINK_MODES, SHOT_VIEWER_ASSET_TYPE_GROUPS): confirm with Kitsu.
• Values marked TODO in config.py wait for production specs.