malkuthro
f9acb05ce2
Reorganize docs/investigations/ into numbered topic folders, each
self-contained with narrative + upstream pin + patches + per-run snapshots.
Add a generic sync helper that mirrors the dev-sync pattern for any
investigation's third-party node modifications.
Structure (new):
docs/investigations/
00_LTX23-base-1-step/README.md (rename of ltx-director-4k-transitions.md)
01_LTX23-audio-file-lipsync/
README.md -- problem, mechanism, patches, reversion, promotion
upstream.json -- repo + version + pinned commit + sync target env + files
patches/ -- source of truth for modified upstream files
ltx_director.py -- adds `relay_overrides` multiline JSON input
prompt_relay.py -- per-segment sigma per Prompt-Relay paper formula
runs/
LOOP.md -- iteration protocol
log.md -- rolling table (empty header for now)
Sync helper:
scripts/sync_investigation_patches.py <NN>_<topic> [--dry-run]
- Reads upstream.json for target env var + file list
- Backs up the target's current state once per day (<file>.bak.<YYYYMMDD>)
- Worktree-aware: falls back to MAIN's .env via git rev-parse --git-common-dir
- Prints a two-line report matching scripts/sync_to_dev.py shape
- Per-investigation trigger phrase via `trigger:` key (sync-audio for #177)
Env:
.env.example -- documents new KOLOOK_WHATDREAMSCOST_PATH
.env -- local path set
Glossary updates (docs/reference/glossary.md):
+ Investigation folder
+ JSON file folder
+ Loop
+ Run
+ Investigation patches
+ sync_investigation_patches.py
Closes the workflow gap from #177: MAIN is now the source of truth for
investigation patches; the live install is a sync destination only. No
manual file copying between iterations — `sync-audio` does it.
Reference
Lookup material — definitions, lists, spec sheets. Anything someone would search for to answer a "what is X?" or "which nodes do Y?" question.
Contents
| File | What it is |
|---|---|
glossary.md |
Plain-English definitions for the terms used in this repo's workflow (MAIN, fork, namespace suffix, sibling project, etc.) |
versioning.md |
The three independent version axes in this codebase (pack version, fork wrapper version, upstream pinned commit) — what each one means, when each one bumps, and which skill/doc owns it |
comfyUI_nodes-inventory_by_NAME.png |
Screenshot inventory of all currently-registered nodes by display name (helpful for matching what you see in ComfyUI back to the source files) |
When to add a reference doc here
- It's a fact, not a procedure (procedures go in
../maintainers/) - It's something someone would look up, not read top-to-bottom (narrative content goes in
../user_guide/) - It's worth keeping in sync as the codebase evolves