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>`
     (45 checks, "All checks passed"). `/_test/publish` and `/_test/download` simulate a new
     publish and a requested revision reaching this site.
  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. In Blender 5.2 it also replaces the Library itself (renamed
  after its file, custom properties gone): `library.update()` finds it by path and restores
  the name and tags.
- Removing a library leaves the libraries it linked indirectly (e.g. Blender's
  `geometry_nodes_essentials.blend`): `remove_unused_libraries()` drops the ones whose data
  is no longer used, never a managed library.
- 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).

## Real Libreflow (first run, 2026-10-27)

- Kitsu asset types: `main_character`, `secondary_character`, `tertiary_character`,
  `main_props`, `secondary_props`, `set_props`, `vehicles`, `bg_location`, `bg_set`,
  `skies`, `setdress_bank`. The fake server uses the same names.
- Paths come back as Windows paths with backslashes; `comment` can be `null`.
- Set dressing publishes (`setdress_low`) hold a whole layout scene: the set is the
  `environments` collection, next to `lights`, `cameras`, `characters`, `_unused`.
- Tested live: connection, context, casting, load (instance and override), version switch
  and update, remove, assetize errors, one request (`car_paul` modeling.blend v001 →
  `Requested`). Not tested: an actual assetize publish (it writes to production).
  New wtdcmds commands need every Libreflow session restarted (a running one keeps the
  old code and answers 404).

## Open points

- Override vs instance per asset type (`SCENE_MANAGER_LINK_MODES`), and the file patterns
  of sets (`setdress_low` seen on one asset only): confirm with production.
- The server picks the first file matching a pattern even when it is not on this site,
  while another matching file is (e.g. `car_paul`: `modeling/modeling.blend` v001 not
  available, `modeling/tes_modeling.blend` v002 available).
- Values marked TODO in `config.py` wait for production specs.