malkuthro-ComfyUI-Koolook/.github/copilot-instructions.md

GitHub Copilot — repo orientation

Thin pointer. The canonical agent context lives in CLAUDE.md at the repo root — read that first for source-of-truth conventions, dev-sync rules, release rules, fork policy, and trigger phrases. This file only carries the high-stability orientation that helps Copilot place a request before it follows links.

What this repo is

ComfyUI-Koolook is a custom-node pack for ComfyUI. Two shipped surfaces:

1. Kforge Labs sidebar — the main user-facing experience. A ComfyUI sidebar tab that saves favorite nodes, workflows (with subdirectories + archive + tags + reusable modules), and full-state snapshots to a configurable on-disk library.

   • Front-end entry: web/koolook_sidebar.js; module bodies under web/sidebar/.
   • Back-end snapshot/preset routes: koolook_routes.py (registers /koolook/presets/* aiohttp routes on ComfyUI's PromptServer).
   • Bundled visual onboarding guide: web/guide/index.html (also opened in-app via the sidebar's Tools-row Help button).

2. Koolook custom nodes — Python node classes at the repo root, each exposing the standard ComfyUI node contract (INPUT_TYPES, RETURN_TYPES, RETURN_NAMES, FUNCTION, CATEGORY):

   • k_easy_wan22_prompt.py → EasyWan22Prompt (reads config.json at import time — edits to config.json need a ComfyUI restart).
   • k_easy_resize.py → EasyResize_Koolook (deprecated alias EasyResize still registered for back-compat).
   • k_ai_pipeline.py → EasyAIPipeline (paired with front-end widgets in web/ai_pipeline.js).
   • k_easy_image_batch.py → easy_ImageBatch.
   • k_easy_track.py → KoolookLoadCameraPosesAbsolute.
   • k_video_combine.py → Easy_VideoCombine (runtime subclass of VHS VideoCombine; self-skips if VHS not installed).
   • Radiance VAE wrappers under forks/radiance_koolook/versions/v2_3_3/ → Easy_hdr_VAE_encode, Easy_hdr_VAE_decode.

__init__.py imports each module's NODE_CLASS_MAPPINGS / NODE_DISPLAY_NAME_MAPPINGS and exposes the merged set plus WEB_DIRECTORY.

Things that bite if you don't know them

• Backward compatibility is opt-in for Koolook-created nodes only (the root k_*.py custom nodes). For those, make the cleanest change by default — rename/drop/reorder IDs, inputs, and outputs freely, no aliases or _v2 suffixes — unless the maintainer says check backward compatibility. Fork nodes are different: anything under forks/ keeps full back-compat discipline by default (never rename a fork ID in saved workflows, version via new suffix/namespace, keep the __koolook_vX_Y_Z collision suffix). See docs/maintainers/node-versioning.md and CLAUDE.md → Change management.
• Third-party code stays out of MAIN. Modified fork code lives under forks/<name>/versions/<vX_Y_Z>/; raw upstream checkouts live in ../ComfyUI-Forks/. See forks/README.md and forks/THIRD_PARTY.md.
• dev-sync is user-triggered only. Never run it automatically (e.g. after a commit, after a merge, on session end). The maintainer runs parallel worktrees and an unsolicited sync overwrites whatever they're reviewing in their live ComfyUI. Wait for the explicit phrase. Full rules in CLAUDE.md.
• UI work needs visual QA. See AGENTS.md — open the changed page in a browser, take a screenshot, verify before claiming done.
• Three independent version axes (pack version / fork wrapper version / upstream pinned commit) — see docs/reference/versioning.md before any version bump.

Where to look next

• CLAUDE.md — full project conventions and protocols
• docs/maintainers/ — release procedure, dev-sync loop, registry API, sidebar starter preset, workflows-sidebar reference
• docs/reference/ — glossary, versioning model
• docs/user_guide/ — per-node end-user docs
• README.md — public landing page + install
• CHANGELOG.md — what changed, in detail