Merge remote-tracking branch 'origin/main' into dev

# Conflicts:
#	CHANGELOG.md
#	README.md
#	conditioning.py
#	docs/FunPackVideoRefinerV2.md
#	pyproject.toml

CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## [2.2.2] - 2026-05-13
+## [2.3.4] - 2026-05-13
 
 ### Added
 
@@ -8,7 +8,7 @@ Added searchable LoRA picking to `FunPack Apply LoRA Weights`. The compact row U
 
 Added optional `clip_vision_output`, `source_image`, and `negative_prompt` inputs to `FunPack Video Refiner V2`.
 
-Added a final `modified_negative` conditioning output to `FunPack Video Refiner V2`. When negative repair has prompt text to encode, the node returns repaired negative conditioning; otherwise it returns an empty conditioning list.
+Added a final `modified_negative` conditioning output to `FunPack Video Refiner V2`. When negative repair has prompt text to encode and `CLIP` is connected, the node returns repaired negative conditioning; otherwise it returns an empty conditioning list.
 
 Added advisory V2 vision context storage for source image dimensions, aspect ratio bucket, image fingerprint, CLIP Vision tensor summaries, and changed-image detection. Vision context is diagnostic only and is not blended into positive conditioning.
 
@@ -22,6 +22,56 @@ Reduced repeated Refiner V2 CLIP model calls by caching category and phrase enco
 
 Updated negative repair to persist poorly rated or wrong-context tags and append them to future negative prompts before encoding negative conditioning.
 
+## [2.3.3] - 2026-05-08
+
+### Fixed
+
+Fixed Refiner V2 so `CLIP` and pre-encoded `positive_conditioning` can both be optional inputs. When `CLIP` is connected, V2 keeps owning prompt encoding as before. When `CLIP` is not connected but `positive_conditioning` is connected, V2 accepts the finished Gemma3/LTX2 conditioning, uses the prompt for analysis, and loads only the Gemma3 tokenizer.
+
+## [2.3.2] - 2026-05-08
+
+### Added
+
+Added Refiner V2 original-intent alignment memory. When `user_intent_prompt` stays the same but an enhancer produces different `positive_prompt` variants, the refiner now remembers intent-enhance pairs, which variants rated well, which original-intent phrases were omitted, and which enhancer-only phrases were rejected.
+
+### Fixed
+
+Fixed Refiner V2 so learned original-intent omissions can be restored on later runs, while repeatedly rejected enhancer-only additions can be removed before encoding. Rejected enhancer-only full words and adjacent word pairs are stored as omit evidence for that original intent.
+
+## [2.3.1] - 2026-05-08
+
+### Fixed
+
+Fixed Refiner V2 Prompt Repair so missing/wrong ratings only repair from the current prompt or explicit user intent, instead of pulling unrelated learned favorite actions, details, quality cues, camera moves, or styles from memory.
+
+Fixed Prompt Repair memory matching so the same word with different neighboring prompt context is treated as different evidence.
+
+Fixed vague raw user intent handling so prompts like `Figure it out` let the enhanced `positive_prompt` drive repair matching when available.
+
+## [2.3.0] - 2026-05-08
+
+### Added
+
+Added `Wrong appearance` rating to `FunPack Video Refiner V2` for outputs contaminated by remembered clothing, character, subject, or background concepts.
+
+Added `FunPack Refinement Key Loader`, with a selectable key dropdown, create-on-load behavior, and browser-side JSON import/export buttons.
+
+Added a Discord-friendly Refiner V2 quick guide for new users.
+
+### Changed
+
+Updated Refiner V2 Prompt Repair so it only auto-adds safe repair concepts such as action, camera, details, quality, and style. Appearance, subject/character, and environment/background concepts are now blocked from Prompt Repair.
+
+Updated `I'm Feeling Lucky` in Refiner V2 so appearance, subject/character, and environment/background memory is not auto-injected unless the user explicitly includes that phrase in the current prompt.
+
+Updated legacy Void/Lucky token-bank selection to skip appearance, subject/character, and environment/background tokens.
+
+Updated Refiner V2 and `FunPack Apply LoRA Weights` so both can accept a linked refinement key from `FunPack Refinement Key Loader`.
+
+### Fixed
+
+Fixed appearance bleed-over where highly liked clothing or character tags could reappear in unrelated image-to-video prompts.
+
 ## [2.2.1] - 2026-05-07
 
 ### Fixed

README.md

@@ -2,7 +2,7 @@
 
 A set of ComfyUI nodes for experimenting with video generation workflows based on WAN, HunyuanVideo, LTX, and similar models.
 
-## Updates in 2.2.2
+## Updates in 2.3.4
 
 Added searchable LoRA selection to `FunPack Apply LoRA Weights` while keeping the compact row UI and serialized LoRA stack format.
 
@@ -10,6 +10,34 @@ Added advisory image/CLIP Vision context and repaired negative conditioning to `
 
 Added an opt-in experimental early velocity bias mode to `FunPack Hybrid Euler 2S Sampler` for capturing/applying averaged early denoise directions around normalized sigma 0.9 and 0.8.
 
+## Updates in 2.3.3
+
+Refiner V2 now supports the restored pre-encoded conditioning workflow: connect `positive_conditioning` without `CLIP` and it accepts the finished Gemma3/LTX2 conditioning while loading only the Gemma3 tokenizer. If `CLIP` is connected, V2 still encodes the prompt itself and ignores the fallback conditioning path.
+
+## Updates in 2.3.2
+
+Refiner V2 now learns original-intent alignment when `user_intent_prompt` stays the same but an enhancer gives different `positive_prompt` variants. Ratings teach it which intent-enhance pairs represented the original request, which original phrases were missing, and which enhancer-only additions were rejected.
+
+Learned original-intent omissions can now be restored on later runs, while repeatedly rejected enhancer-only full words and adjacent word pairs can be omitted before encoding.
+
+## Updates in 2.3.1
+
+Refiner V2 Prompt Repair now keeps all missing/wrong ratings tied to the current prompt or explicit user intent. Learned favorite actions, details, quality cues, camera moves, and styles are not repaired into unrelated requests just because they scored well before.
+
+Prompt Repair now treats the same word in different neighbor contexts as separate evidence, so a liked phrase does not automatically transfer to a different request that happens to share one word.
+
+When the optional raw user intent is vague, such as `Figure it out`, Refiner V2 now treats the enhanced `positive_prompt` as the stronger repair anchor.
+
+## Updates in 2.3.0
+
+Refiner V2 now blocks learned appearance, character, subject, and background concepts from Prompt Repair, Lucky auto-injection, and legacy Void memory unless the current prompt explicitly asks for them.
+
+Added `Wrong appearance` for outputs polluted by remembered clothing or character traits. This suppresses the responsible appearance memory without penalizing unrelated action, camera, detail, or quality learning.
+
+Added `FunPack Refinement Key Loader` for selecting, creating, importing, and exporting Refiner V2 keys. The loader can feed both Refiner V2 and `FunPack Apply LoRA Weights`.
+
+Added a paste-friendly [`Refiner V2 quick guide`](docs/FunPackVideoRefinerV2QuickGuide.md) for new users.
+
 ## Updates in 2.2.1
 
 Fixed Refiner V2 prompt phrase categorization so background, appearance, quality, camera, and action phrases stay aligned before the node updates Lucky memory or LoRA suggestions.
@@ -76,6 +104,7 @@ Per-node documentation is available in the [`docs`](docs) folder.
 Start with:
 
 - [`docs/FunPackVideoRefinerV2.md`](docs/FunPackVideoRefinerV2.md) for `FunPack Video Refiner V2`
+- [`docs/FunPackVideoRefinerV2QuickGuide.md`](docs/FunPackVideoRefinerV2QuickGuide.md) for a short Discord-friendly Refiner V2 guide
 - [`docs/FunPackLoraWorkflow.md`](docs/FunPackLoraWorkflow.md) for the LoRA/refiner helper workflow
 
 Version history is available in [CHANGELOG.md](CHANGELOG.md).

__init__.py

@@ -18,7 +18,7 @@ if __package__:
     from .model_management import FunPackApplyLoraWeights, FunPackLoraLoader
     from .samplers import FunPackHybridEuler2SSampler
     from .context_transition import FunPackContextTransitionWindows
-    from .templates import FunPackTemplateManager
+    from .templates import FunPackRefinementKeyLoader, FunPackTemplateManager
 else:
     # Standalone tests may not have the full ComfyUI/CUDA runtime loaded.
     from conditioning import (
@@ -56,8 +56,9 @@ else:
     except Exception:
         FunPackContextTransitionWindows = None
     try:
-        from templates import FunPackTemplateManager
+        from templates import FunPackRefinementKeyLoader, FunPackTemplateManager
     except Exception:
+        FunPackRefinementKeyLoader = None
         FunPackTemplateManager = None
 
 WEB_DIRECTORY = "./web"
@@ -77,6 +78,7 @@ NODE_CLASS_MAPPINGS = {
     "FunPackContextTransitionWindows": FunPackContextTransitionWindows,
     "FunPackApplyLoraWeights": FunPackApplyLoraWeights,
     "FunPackLoraLoader": FunPackLoraLoader,
+    "FunPackRefinementKeyLoader": FunPackRefinementKeyLoader,
     "FunPackTemplateManager": FunPackTemplateManager,
 }
 NODE_CLASS_MAPPINGS = {name: cls for name, cls in NODE_CLASS_MAPPINGS.items() if cls is not None}
@@ -96,6 +98,7 @@ NODE_DISPLAY_NAME_MAPPINGS = {
     "FunPackContextTransitionWindows": "FunPack Context Transition Windows",
     "FunPackApplyLoraWeights": "FunPack Apply LoRA Weights",
     "FunPackLoraLoader": "FunPack LoRA Loader",
+    "FunPackRefinementKeyLoader": "FunPack Refinement Key Loader",
     "FunPackTemplateManager": "FunPack Template Manager",
 }
 

docs/FunPackVideoRefinerV2.md

@@ -17,6 +17,10 @@ V2 replaces the old `FunPack Video Refiner` public node in version `2.2.0`. It u
 - `Missing action`
 - `Missing quality`
 - `Missing details + action`
+- `Wrong details`
+- `Wrong action`
+- `Wrong details + action`
+- `Wrong appearance`
 - `Missing details + quality`
 - `Missing action + quality`
 - `Awful`
@@ -24,8 +28,12 @@ V2 replaces the old `FunPack Video Refiner` public node in version `2.2.0`. It u
 
 Older `Missing concept` labels are accepted as aliases for `Missing action`.
 
+Use `Wrong appearance` when the video is polluted by remembered clothing, character traits, subject identity, or background concepts that were not requested for the current image. This suppresses those concepts from future auto-injection without deleting them for explicit prompts.
+
 **refinement_key**: V2 session key. V2 stores separate `refine_v2` state under this key.
 
+**refinement_key_input**: Optional linked key input, usually from `FunPack Refinement Key Loader`. When connected, it overrides the text widget.
+
 **seed**: Optional seed for deterministic exploration paths.
 
 **reset_session**: Clears the V2 session state for the selected key.
@@ -36,10 +44,26 @@ Older `Missing concept` labels are accepted as aliases for `Missing action`.
 
 **source_image**: Optional source image/frame batch. V2 stores width, height, aspect ratio bucket, and a small fingerprint so it can report whether the input image changed between runs.
 
-**negative_prompt**: Optional negative prompt. V2 can persistently add poorly rated or wrong-context tags to this prompt, then encode the repaired prompt as negative conditioning.
+**negative_prompt**: Optional negative prompt. V2 can persistently add poorly rated or wrong-context tags to this prompt, then encode the repaired prompt as negative conditioning when `CLIP` is connected.
+
+**user_intent_prompt**: Optional raw/original request. When connected, V2 compares it with the enhanced `positive_prompt`, stores intent-enhance pairs, remembers all provided full-word and adjacent word-pair tokens for that intent, and can omit enhancer-only tokens that repeatedly led to bad ratings.
 
 **im_feeling_lucky**: When enabled, V2 composes a learned prompt from rated phrase memory and encodes it through the connected CLIP. When disabled, V2 may still store Lucky memory from rated runs, but it does not compose or apply a Lucky prompt.
 
+## Appearance Safety
+
+Refiner V2 treats image-to-video appearance as image-owned by default. Learned appearance, subject/character, and environment/background phrases are not auto-added by Prompt Repair or Lucky unless they are already present in the current prompt.
+
+Prompt Repair is only for motion, camera work, small non-identity details, quality, and style. It will not add clothing, body traits, character identity, or background phrases from memory.
+
+Legacy Void memory also skips appearance, subject/character, and environment/background tokens so old token-bank preferences cannot reintroduce those concepts.
+
+## Refinement Key Loader
+
+`FunPack Refinement Key Loader` lists existing V2 keys, creates a typed key when none is selected, and exposes `Import`, `Export`, and `Refresh` buttons in the browser UI.
+
+Connect its `refinement_key` output to Refiner V2's `refinement_key_input` and to `FunPack Apply LoRA Weights`' `refinement_key_input` so both nodes use the same memory key.
+
 ## Outputs
 
 **modified_positive**: Refined positive conditioning.
@@ -50,7 +74,7 @@ Older `Missing concept` labels are accepted as aliases for `Missing action`.
 
 **loss_graph**: V2 learning loss graph.
 
-**modified_negative**: Repaired negative conditioning. If the negative prompt is empty and V2 has no stored poor-rated tags to add, this output is empty.
+**modified_negative**: Repaired negative conditioning. If the negative prompt is empty, no stored poor-rated tags are available, or `CLIP` is not connected, this output is empty.
 
 ## Vision Context
 
@@ -60,7 +84,7 @@ Vision inputs are intentionally advisory in this version. The refiner stores sou
 
 When ratings mark a prior run as `Awful`, `Wrong details`, `Wrong action`, or otherwise strongly negative, V2 stores matching poorly rated prompt phrases as negative repair tags. Future runs append the strongest stored tags to `negative_prompt` before encoding `modified_negative`.
 
-Positive prompt repair still uses learned phrase memory. Repaired phrases preserve stopwords and phrase text, so phrases like `running through the street` stay intact instead of being collapsed to only content tokens.
+Positive prompt repair still uses learned phrase memory and intent alignment. Repaired phrases preserve stopwords and phrase text, so phrases like `running through the street` stay intact instead of being collapsed to only content tokens.
 
 ## Removed From V2
 

docs/FunPackVideoRefinerV2QuickGuide.md

@@ -0,0 +1,37 @@
+# Refiner V2 Quick Guide
+
+`FunPack Video Refiner V2` is a prompt memory node. It takes your positive prompt, encodes it through the connected CLIP, remembers how you rated the previous output, and slowly learns which actions, camera moves, details, quality cues, and style cues work for your workflows.
+
+It does not look at the finished video pixels. It does not magically know what is inside your input image. It does not replace clear prompting. In image-to-video, it now treats character appearance, clothing, subject identity, and background as image-owned by default, so it should not inject old remembered outfits or characters into a new image unless you explicitly prompt them.
+
+## How To Use It
+
+1. Add `FunPack Video Refiner V2` before your sampler where positive conditioning is encoded.
+2. Connect your `CLIP`.
+3. Type a `refinement_key`, or use `FunPack Refinement Key Loader` and connect its output into `refinement_key_input`.
+4. First run only seeds memory. Generate once, look at the result, then rate that result on the next run with the same key.
+5. Use `Perfect` when the output is good and should be remembered.
+6. Use `Missing action` when the requested motion did not happen.
+7. Use `Missing details` when small non-identity details are weak, like smoke, reflections, particles, hand contact, object interaction, or secondary motion.
+8. Use `Missing quality` when the idea is right but the result is messy or ugly.
+9. Use `Wrong action`, `Wrong details`, or `Wrong details + action` when the video looks usable but did the wrong thing.
+10. Use `Wrong appearance` when Refiner/Lucky brought in unwanted clothing, face, body, character, subject, or background memory.
+11. Use `-Just forget it-` for broken runs, bad seeds, workflow mistakes, model failures, or anything you do not want learned.
+
+## Lucky Mode
+
+`I'm Feeling Lucky` composes a prompt from learned memory. It is useful when you want the node to suggest motion, camera, detail, quality, or style ideas from previous liked outputs.
+
+Lucky should not auto-add remembered outfits, character traits, subjects, or backgrounds anymore. If you want an appearance item, write it directly in the prompt.
+
+## Examples
+
+If your prompt says `person smoking and exhaling smoke` but the video only shows a puff with no exhale, rate `Missing details` or `Missing action`, depending on what matters most. This teaches the key that smoke/exhale matters in that prompt context, without globally banning smoking.
+
+If you liked `white tights` in older prompts but your new input image is only a portrait face, and Lucky tries to bring tights into the scene, rate `Wrong appearance`. That tells Refiner to suppress that appearance memory from auto-injection while still allowing `white tights` when you explicitly type it.
+
+If the camera should push in, orbit, pan, or change framing and it stays static, rate `Missing action` or `Wrong action`. Camera movement belongs to the action/camera side of memory, so it remains safe for repair and Lucky.
+
+## Key Loader
+
+Use `FunPack Refinement Key Loader` when you want a reusable key dropdown or want to move keys between workflows/machines. Its `Import` and `Export` buttons save/load the key as JSON. Connect the loader to both Refiner V2 and `FunPack Apply LoRA Weights` so LoRA suggestions and prompt memory use the same key.

funpack.py

@@ -19,7 +19,7 @@ try:
     from .model_management import FunPackApplyLoraWeights, FunPackLoraLoader
     from .samplers import FunPackHybridEuler2SSampler, sample_funpack_hybrid_euler_2s
     from .context_transition import FunPackContextTransitionWindows
-    from .templates import FunPackTemplateManager
+    from .templates import FunPackRefinementKeyLoader, FunPackTemplateManager
 except ImportError:
     from conditioning import (
         FunPackLorebookEnhancer,
@@ -38,7 +38,7 @@ except ImportError:
     from model_management import FunPackApplyLoraWeights, FunPackLoraLoader
     from samplers import FunPackHybridEuler2SSampler, sample_funpack_hybrid_euler_2s
     from context_transition import FunPackContextTransitionWindows
-    from templates import FunPackTemplateManager
+    from templates import FunPackRefinementKeyLoader, FunPackTemplateManager
 
     NODE_CLASS_MAPPINGS = {
         "FunPackPromptCombiner": FunPackPromptCombiner,
@@ -55,6 +55,7 @@ except ImportError:
         "FunPackContextTransitionWindows": FunPackContextTransitionWindows,
         "FunPackApplyLoraWeights": FunPackApplyLoraWeights,
         "FunPackLoraLoader": FunPackLoraLoader,
+        "FunPackRefinementKeyLoader": FunPackRefinementKeyLoader,
         "FunPackTemplateManager": FunPackTemplateManager,
     }
 
@@ -73,6 +74,7 @@ except ImportError:
         "FunPackContextTransitionWindows": "FunPack Context Transition Windows",
         "FunPackApplyLoraWeights": "FunPack Apply LoRA Weights",
         "FunPackLoraLoader": "FunPack LoRA Loader",
+        "FunPackRefinementKeyLoader": "FunPack Refinement Key Loader",
         "FunPackTemplateManager": "FunPack Template Manager",
     }
 
@@ -93,6 +95,7 @@ __all__ = [
     "FunPackStoryMemLastFrameExtractor",
     "FunPackApplyLoraWeights",
     "FunPackLoraLoader",
+    "FunPackRefinementKeyLoader",
     "FunPackTemplateManager",
     "sample_funpack_hybrid_euler_2s",
 ]

model_management.py

@@ -189,6 +189,12 @@ class FunPackApplyLoraWeights:
             any_type,
             {
                 "lora_list": ("STRING", {"default": "[]", "multiline": False}),
+                "refinement_key_input": ("STRING", {
+                    "default": "",
+                    "multiline": False,
+                    "forceInput": True,
+                    "tooltip": "Optional linked refinement key, for example from FunPack Refinement Key Loader. Overrides the refinement_key widget when connected.",
+                }),
                 "lora_0": (loras, {"default": "None"}),
                 "lora_0_type": (LORA_TYPES, {"default": "general"}),
                 "lora_0_base_weight": (
@@ -358,6 +364,9 @@ class FunPackApplyLoraWeights:
         return abs(float(saved_base) - float(entry["base_model_weight"])) <= 1e-6
 
     def apply_lora_weights(self, positive_prompt, refinement_key, mode, per_block=False, **kwargs):
+        linked_refinement_key = str(kwargs.pop("refinement_key_input", "") or "").strip()
+        if linked_refinement_key:
+            refinement_key = linked_refinement_key
         mode = (mode or "ltx2").lower()
         per_block = coerce_bool(per_block)
         prompt_key = prompt_key_for_mode(positive_prompt, mode)

pyproject.toml

@@ -2,7 +2,7 @@
 [project]
 name = "ComfyUI-FunPack" # Unique identifier for your node. Immutable after creation.
 description = "A set of nodes for experiments with video generation models, including prompt refinement, adaptive LoRA weight workflows, story tools, video stitching, lorebook enhancement and more."
-version = "2.2.2" # Custom Node version. Must be semantically versioned.
+version = "2.3.4" # Custom Node version. Must be semantically versioned.
 license = { text = "GNU GPL v3" }
 dependencies  = [] # Filled in from requirements.txt
 

templates.py

@@ -27,6 +27,7 @@ except ImportError:
 
 
 TEMPLATE_NONE = "-None-"
+REFINEMENT_KEY_NONE = "-None-"
 TEMPLATE_DB_VERSION = 1
 WILDCARD_RE = re.compile(r"\{([^{}]*\|[^{}]*)\}")
 
@@ -46,6 +47,120 @@ def template_store_path():
     return os.path.join(template_store_dir(), "templates.json")
 
 
+def refinement_store_dir():
+    return os.path.join(os.path.dirname(os.path.abspath(__file__)), "refinements")
+
+
+def normalize_refinement_key(value):
+    value = str(value or "").strip()
+    if not value or value == REFINEMENT_KEY_NONE:
+        return ""
+    return value
+
+
+def empty_v2_refinement_state(refinement_key):
+    return {
+        "version": 2,
+        "refinement_key": refinement_key,
+        "state_namespace": "clip",
+        "global": {
+            "total_iterations": 0,
+            "avg_reward_ema": 0.0,
+            "good_streak": 0,
+            "bad_streak": 0,
+            "last_rating_label": "Initial discovery",
+            "last_missing_axes": [],
+            "phrase_memory": {},
+            "axis_conditioning_memory": {},
+            "lora_weight_memory": {},
+            "preferred_context_memory": {},
+            "loss_history": [],
+        },
+        "prompt_histories": {},
+        "last_run": None,
+    }
+
+
+def refinement_key_path(refinement_key):
+    return refinement_state_path(refinement_key, "clip", prefix="refine_v2")
+
+
+def normalize_refinement_state(data, fallback_key=""):
+    if not isinstance(data, dict):
+        return None, ""
+    key = normalize_refinement_key(data.get("refinement_key") or fallback_key)
+    if not key:
+        return None, ""
+    state = dict(data)
+    state["version"] = 2
+    state["refinement_key"] = key
+    state["state_namespace"] = "clip"
+    state.setdefault("global", {})
+    state["global"].setdefault("phrase_memory", {})
+    state["global"].setdefault("axis_conditioning_memory", {})
+    state["global"].setdefault("lora_weight_memory", {})
+    state["global"].setdefault("preferred_context_memory", {})
+    state["global"].setdefault("loss_history", [])
+    state.setdefault("prompt_histories", {})
+    state.setdefault("last_run", None)
+    return state, key
+
+
+def load_refinement_key_state(refinement_key, create=False):
+    key = normalize_refinement_key(refinement_key)
+    if not key:
+        return None, "", "No refinement key selected."
+    path = refinement_key_path(key)
+    if os.path.exists(path):
+        try:
+            with open(path, "r", encoding="utf-8") as file:
+                data = json.load(file)
+            state, loaded_key = normalize_refinement_state(data, key)
+            if state is None:
+                return None, key, f"Refinement key '{key}' is unreadable."
+            return state, loaded_key, f"Loaded refinement key '{loaded_key}'."
+        except (json.JSONDecodeError, OSError, ValueError):
+            return None, key, f"Refinement key '{key}' is unreadable."
+    if not create:
+        return None, key, f"Refinement key '{key}' does not exist."
+    state = empty_v2_refinement_state(key)
+    save_refinement_key_state(state, key)
+    return state, key, f"Created refinement key '{key}'."
+
+
+def save_refinement_key_state(state, refinement_key):
+    key = normalize_refinement_key(refinement_key)
+    if not key:
+        return ""
+    state, key = normalize_refinement_state(state, key)
+    if state is None:
+        return ""
+    path = refinement_key_path(key)
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w", encoding="utf-8") as file:
+        json.dump(state, file, indent=2)
+    return path
+
+
+def refinement_key_names():
+    keys = set()
+    directory = refinement_store_dir()
+    if os.path.isdir(directory):
+        for filename in os.listdir(directory):
+            if not filename.startswith("refine_v2_") or not filename.endswith(".json"):
+                continue
+            path = os.path.join(directory, filename)
+            try:
+                with open(path, "r", encoding="utf-8") as file:
+                    data = json.load(file)
+                key = normalize_refinement_key(data.get("refinement_key") if isinstance(data, dict) else "")
+                if key:
+                    keys.add(key)
+            except (json.JSONDecodeError, OSError, ValueError):
+                continue
+    return [REFINEMENT_KEY_NONE] + sorted(keys)
+
+
 def empty_template_db():
     return {
         "version": TEMPLATE_DB_VERSION,
@@ -322,6 +437,79 @@ async def funpack_templates_import(request):
     return web.json_response({"imported": imported, "templates": template_names()})
 
 
+@PromptServer.instance.routes.get("/funpack/refinement_keys")
+async def funpack_refinement_keys(_):
+    return web.json_response(
+        {"keys": refinement_key_names(), "path": refinement_store_dir()},
+        headers={"Cache-Control": "no-store, max-age=0"},
+    )
+
+
+@PromptServer.instance.routes.get("/funpack/refinement_keys/export")
+async def funpack_refinement_keys_export(request):
+    key = normalize_refinement_key(request.query.get("key", ""))
+    state, loaded_key, status = load_refinement_key_state(key, create=False)
+    if state is None:
+        return web.json_response({"error": status}, status=404)
+    return web.json_response(
+        state,
+        headers={
+            "Cache-Control": "no-store, max-age=0",
+            "Content-Disposition": f"attachment; filename=funpack_refinement_{loaded_key}.json",
+        },
+    )
+
+
+@PromptServer.instance.routes.post("/funpack/refinement_keys/import")
+async def funpack_refinement_keys_import(request):
+    incoming = await request.json()
+    if isinstance(incoming, dict) and isinstance(incoming.get("state"), dict):
+        incoming = incoming["state"]
+    state, key = normalize_refinement_state(incoming)
+    if state is None:
+        return web.json_response({"error": "Imported file is not a valid V2 refinement key JSON."}, status=400)
+    path = save_refinement_key_state(state, key)
+    if not path:
+        return web.json_response({"error": "Could not save imported refinement key."}, status=400)
+    return web.json_response({"imported": key, "keys": refinement_key_names()})
+
+
+class FunPackRefinementKeyLoader:
+    CATEGORY = "FunPack/Refinement"
+    RETURN_TYPES = ("STRING", "STRING")
+    RETURN_NAMES = ("refinement_key", "status")
+    FUNCTION = "load_refinement_key"
+    OUTPUT_NODE = True
+    DESCRIPTION = "Loads, creates, imports, and exports FunPack Video Refiner V2 refinement keys."
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "refinement_key": (refinement_key_names(), {"default": REFINEMENT_KEY_NONE}),
+                "key_name": ("STRING", {"default": "", "multiline": False}),
+                "create_if_missing": ("BOOLEAN", {"default": True}),
+            },
+        }
+
+    @classmethod
+    def IS_CHANGED(cls, **kwargs):
+        return float("nan")
+
+    @classmethod
+    def VALIDATE_INPUTS(cls, refinement_key=None, **kwargs):
+        return True
+
+    def load_refinement_key(self, refinement_key, key_name, create_if_missing=True):
+        selected = normalize_refinement_key(refinement_key)
+        typed = normalize_refinement_key(key_name)
+        target = selected or typed
+        if not target:
+            return ("", "No refinement key selected. Pick an existing key or type a new key name.")
+        _, loaded_key, status = load_refinement_key_state(target, create=bool(create_if_missing))
+        return (loaded_key if loaded_key else target, status)
+
+
 class FunPackTemplateManager:
     CATEGORY = "FunPack/Templates"
     RETURN_TYPES = ("STRING", "STRING", "STRING", "SIGMAS", "CONDITIONING", "FUNPACK_LORA_STACK", "STRING", "STRING")

tests/test_v2_category_alignment.py

@@ -68,6 +68,14 @@ def prompt_items(refiner, words):
     ]
 
 
+def prompt_phrases(refiner, prompt, global_state=None):
+    return refiner._v2_classify_phrases(
+        None,
+        refiner._ordered_prompt_phrases(prompt),
+        global_state or {"phrase_memory": {}},
+    )
+
+
 def train_prompt_context(refiner, words, rating_label, global_state=None, iterations=1):
     global_state = global_state or {"phrase_memory": {}}
     phrases = refiner._v2_classify_phrases(None, prompt_items(refiner, words), global_state)
@@ -210,7 +218,10 @@ def test_awful_lora_feedback_reduces_before_missing_axis_boosts():
 
 def test_category_weights_are_recorded_for_every_learning_rating():
     refiner = FunPackVideoRefinerV2()
-    learning_labels = [label for label in V2_RATING_LABELS if label != "-Just forget it-"]
+    learning_labels = [
+        label for label in V2_RATING_LABELS
+        if label not in {"-Just forget it-", "Wrong appearance"}
+    ]
 
     for label in learning_labels:
         entry, _, _ = train_phrase(refiner, f"running test {label}", label)
@@ -221,6 +232,326 @@ def test_category_weights_are_recorded_for_every_learning_rating():
         assert set(entry["effective_category_scores"]) == set(refiner.CATEGORY_DESCRIPTIONS)
 
 
+def test_wrong_appearance_rating_is_available():
+    profile = normalize_refiner_v2_rating("Wrong appearance")
+
+    assert "Wrong appearance" in V2_RATING_LABELS
+    assert profile["key"] == "wrong_appearance"
+    assert profile["wrong_categories"] == ["appearance", "subject", "environment"]
+
+
+def test_prompt_repair_blocks_appearance_subject_and_environment():
+    refiner = FunPackVideoRefinerV2()
+    global_state = {
+        "phrase_memory": {
+            "white tights": {
+                "text": "white tights",
+                "primary": "appearance",
+                "effective_category_scores": refiner._v2_heuristic_scores("white tights"),
+                "wanted_axes": {"details": 3},
+                "score": 6.0,
+                "liked_count": 4,
+            },
+            "detailed background": {
+                "text": "detailed background",
+                "primary": "environment",
+                "effective_category_scores": refiner._v2_heuristic_scores("detailed background"),
+                "wanted_axes": {"details": 3},
+                "score": 6.0,
+                "liked_count": 4,
+            },
+            "female character": {
+                "text": "female character",
+                "primary": "subject",
+                "effective_category_scores": refiner._v2_heuristic_scores("female character"),
+                "wanted_axes": {"details": 3},
+                "score": 6.0,
+                "liked_count": 4,
+            },
+            "tiny smoke curls": {
+                "text": "tiny smoke curls",
+                "primary": "details",
+                "effective_category_scores": refiner._v2_heuristic_scores("tiny smoke curls"),
+                "wanted_axes": {"details": 3},
+                "score": 4.0,
+                "liked_count": 2,
+            },
+        }
+    }
+    profile = normalize_refiner_v2_rating("Missing details")
+    feedback = refiner._v2_axis_feedback(profile, None)
+
+    repaired, _, candidates = refiner._v2_repair_prompt_for_missing_axes(
+        "person smoking",
+        refiner._v2_classify_phrases(None, prompt_items(refiner, ["person smoking"]), global_state),
+        global_state,
+        None,
+        feedback,
+    )
+
+    assert "tiny smoke curls" in repaired
+    assert "white tights" not in repaired
+    assert "detailed background" not in repaired
+    assert "female character" not in repaired
+    assert all(candidate["text"] != "white tights" for candidate in candidates)
+
+
+def test_intent_alignment_learns_missing_original_intent_from_enhancer_variant():
+    refiner = FunPackVideoRefinerV2()
+    global_state = {"phrase_memory": {}, "intent_alignment_memory": {}}
+    intent_prompt = "woman walking through neon rain"
+    enhanced_prompt = "woman smiling, cinematic studio portrait"
+    profile = normalize_refiner_v2_rating("Missing action")
+    feedback = refiner._v2_axis_feedback(profile, None)
+
+    status = refiner._v2_update_intent_alignment_memory(
+        global_state,
+        {
+            "prompt": enhanced_prompt,
+            "phrases": prompt_phrases(refiner, enhanced_prompt, global_state),
+            "intent_prompt": intent_prompt,
+            "intent_phrases": prompt_phrases(refiner, intent_prompt, global_state),
+        },
+        profile,
+        1,
+        feedback,
+    )
+
+    slot = next(iter(global_state["intent_alignment_memory"].values()))
+    missing = slot["missing_intent_phrases"]["woman walking through neon rain"]
+    variant = next(iter(slot["variants"].values()))
+    assert "Intent alignment learned" in status
+    assert missing["score"] > 0.5
+    assert missing["missing_count"] == 1
+    assert variant["missing_intent_count"] == 1
+
+
+def test_intent_alignment_restores_learned_missing_original_phrase():
+    refiner = FunPackVideoRefinerV2()
+    global_state = {"phrase_memory": {}, "intent_alignment_memory": {}}
+    intent_prompt = "woman walking through neon rain"
+    profile = normalize_refiner_v2_rating("Missing action")
+    feedback = refiner._v2_axis_feedback(profile, None)
+    refiner._v2_update_intent_alignment_memory(
+        global_state,
+        {
+            "prompt": "woman smiling, cinematic studio portrait",
+            "phrases": prompt_phrases(refiner, "woman smiling, cinematic studio portrait", global_state),
+            "intent_prompt": intent_prompt,
+            "intent_phrases": prompt_phrases(refiner, intent_prompt, global_state),
+        },
+        profile,
+        1,
+        feedback,
+    )
+
+    aligned, status, adjustments = refiner._v2_apply_intent_alignment_memory(
+        "woman smiling, moody closeup",
+        prompt_phrases(refiner, "woman smiling, moody closeup", global_state),
+        intent_prompt,
+        prompt_phrases(refiner, intent_prompt, global_state),
+        global_state,
+    )
+
+    assert "woman walking through neon rain" in aligned
+    assert "restored 1 original phrase" in status
+    assert adjustments == [
+        {"text": "woman walking through neon rain", "source": "intent_missing", "action": "added"}
+    ]
+
+
+def test_intent_alignment_removes_rejected_enhancer_only_extra():
+    refiner = FunPackVideoRefinerV2()
+    global_state = {"phrase_memory": {}, "intent_alignment_memory": {}}
+    intent_prompt = "woman walking through neon rain"
+    enhanced_prompt = "woman walking through neon rain, white tights"
+    profile = normalize_refiner_v2_rating("Wrong appearance")
+    feedback = refiner._v2_axis_feedback(profile, None)
+    refiner._v2_update_intent_alignment_memory(
+        global_state,
+        {
+            "prompt": enhanced_prompt,
+            "phrases": prompt_phrases(refiner, enhanced_prompt, global_state),
+            "intent_prompt": intent_prompt,
+            "intent_phrases": prompt_phrases(refiner, intent_prompt, global_state),
+        },
+        profile,
+        1,
+        feedback,
+    )
+
+    aligned, status, adjustments = refiner._v2_apply_intent_alignment_memory(
+        enhanced_prompt,
+        prompt_phrases(refiner, enhanced_prompt, global_state),
+        intent_prompt,
+        prompt_phrases(refiner, intent_prompt, global_state),
+        global_state,
+    )
+
+    assert "white tights" not in aligned
+    assert "woman walking through neon rain" in aligned
+    assert "removed 1 rejected enhancer-only phrase" in status
+    assert adjustments == [
+        {"text": "white tights", "source": "enhancer_extra", "action": "removed"}
+    ]
+
+
+def test_intent_alignment_stores_pairs_and_bad_tokens_to_omit():
+    refiner = FunPackVideoRefinerV2()
+    global_state = {"phrase_memory": {}, "intent_alignment_memory": {}}
+    intent_prompt = "woman walking through neon rain"
+    enhanced_prompt = "woman walking through neon rain, white tights"
+    profile = normalize_refiner_v2_rating("Wrong appearance")
+    feedback = refiner._v2_axis_feedback(profile, None)
+
+    refiner._v2_update_intent_alignment_memory(
+        global_state,
+        {
+            "prompt": enhanced_prompt,
+            "phrases": prompt_phrases(refiner, enhanced_prompt, global_state),
+            "intent_prompt": intent_prompt,
+            "intent_phrases": prompt_phrases(refiner, intent_prompt, global_state),
+        },
+        profile,
+        1,
+        feedback,
+    )
+
+    slot = next(iter(global_state["intent_alignment_memory"].values()))
+    pair = next(iter(slot["intent_enhance_pairs"].values()))
+    assert pair["intent_prompt"] == intent_prompt
+    assert pair["positive_prompt"] == enhanced_prompt
+    assert "woman" in slot["provided_tokens"]
+    assert slot["provided_tokens"]["woman"]["omit"] is False
+    assert slot["provided_tokens"]["white"]["omit"] is True
+    assert slot["provided_tokens"]["tights"]["omit"] is True
+    assert slot["provided_tokens"]["white tights"]["kind"] == "pair"
+    assert slot["provided_tokens"]["white tights"]["omit"] is True
+    assert set(slot["bad_tokens"]) >= {"white", "tights", "white tights"}
+
+
+def test_intent_alignment_omits_bad_token_in_new_enhancer_phrase():
+    refiner = FunPackVideoRefinerV2()
+    global_state = {"phrase_memory": {}, "intent_alignment_memory": {}}
+    intent_prompt = "woman walking through neon rain"
+    profile = normalize_refiner_v2_rating("Wrong appearance")
+    feedback = refiner._v2_axis_feedback(profile, None)
+    refiner._v2_update_intent_alignment_memory(
+        global_state,
+        {
+            "prompt": "woman walking through neon rain, white tights",
+            "phrases": prompt_phrases(refiner, "woman walking through neon rain, white tights", global_state),
+            "intent_prompt": intent_prompt,
+            "intent_phrases": prompt_phrases(refiner, intent_prompt, global_state),
+        },
+        profile,
+        1,
+        feedback,
+    )
+
+    aligned, _, adjustments = refiner._v2_apply_intent_alignment_memory(
+        "woman walking through neon rain, red tights",
+        prompt_phrases(refiner, "woman walking through neon rain, red tights", global_state),
+        intent_prompt,
+        prompt_phrases(refiner, intent_prompt, global_state),
+        global_state,
+    )
+
+    assert "red tights" not in aligned
+    assert "woman walking through neon rain" in aligned
+    assert adjustments == [
+        {"text": "red tights", "source": "enhancer_extra", "action": "removed"}
+    ]
+
+
+def test_lucky_skips_appearance_memory_unless_prompt_mentions_it():
+    refiner = FunPackVideoRefinerV2()
+    global_state = {"phrase_memory": {}, "preferred_context_memory": {}}
+    phrases = refiner._v2_classify_phrases(
+        None,
+        prompt_items(refiner, ["white tights", "walking"]),
+        global_state,
+    )
+    profile = normalize_refiner_v2_rating("Perfect")
+    feedback = refiner._v2_axis_feedback(profile, None)
+    refiner._v2_update_phrase_memory(
+        global_state,
+        {"prompt": "white tights walking", "phrases": phrases},
+        profile,
+        1,
+        feedback,
+    )
+
+    lucky_prompt, _ = refiner._v2_compose_lucky_prompt("", [], global_state)
+    explicit_prompt, _ = refiner._v2_compose_lucky_prompt(
+        "white tights",
+        refiner._v2_classify_phrases(None, prompt_items(refiner, ["white tights"]), global_state),
+        global_state,
+    )
+
+    assert "walking" in lucky_prompt
+    assert "white tights" not in lucky_prompt
+    assert "tights" not in lucky_prompt
+    assert "white tights" in explicit_prompt
+
+
+def test_wrong_appearance_suppresses_only_auto_inserted_appearance_memory():
+    refiner = FunPackVideoRefinerV2()
+    global_state = {"phrase_memory": {}, "preferred_context_memory": {}}
+    phrases = refiner._v2_classify_phrases(None, prompt_items(refiner, ["walking"]), global_state)
+    profile = normalize_refiner_v2_rating("Wrong appearance")
+    feedback = refiner._v2_axis_feedback(profile, None)
+
+    refiner._v2_update_phrase_memory(
+        global_state,
+        {
+            "prompt": "walking",
+            "encoded_prompt": "walking, white tights",
+            "phrases": phrases,
+            "repair_candidates": [{"text": "white tights", "axes": ["details"], "score": 3.0, "source": "memory"}],
+        },
+        profile,
+        1,
+        feedback,
+    )
+
+    appearance = global_state["phrase_memory"]["white tights"]
+    motion = global_state["phrase_memory"]["walking"]
+    assert appearance["auto_inject_suppressed"] is True
+    assert appearance["wrong_appearance_count"] >= 1
+    assert motion.get("wrong_appearance_count", 0) == 0
+    assert motion["category_evidence_count"] == 0
+
+
+def test_repeated_wrong_appearance_keeps_entry_out_of_lucky():
+    refiner = FunPackVideoRefinerV2()
+    global_state = {"phrase_memory": {}, "preferred_context_memory": {}}
+    phrases = refiner._v2_classify_phrases(None, prompt_items(refiner, ["walking"]), global_state)
+    profile = normalize_refiner_v2_rating("Wrong appearance")
+    feedback = refiner._v2_axis_feedback(profile, None)
+
+    for iteration in range(2):
+        refiner._v2_update_phrase_memory(
+            global_state,
+            {
+                "prompt": "walking",
+                "encoded_prompt": "walking, white tights",
+                "phrases": phrases,
+                "repair_candidates": [{"text": "white tights", "axes": ["details"], "score": 3.0, "source": "memory"}],
+            },
+            profile,
+            iteration + 1,
+            feedback,
+        )
+
+    global_state["phrase_memory"]["white tights"]["score"] = 6.0
+    global_state["phrase_memory"]["white tights"]["liked_count"] = 8
+    lucky_prompt, _ = refiner._v2_compose_lucky_prompt("", [], global_state)
+
+    assert global_state["phrase_memory"]["white tights"]["auto_inject_blocked_count"] >= 2
+    assert "white tights" not in lucky_prompt
+
+
 def test_forget_rating_skips_category_weight_learning():
     refiner = FunPackVideoRefinerV2()
     global_state = {"phrase_memory": {}}
@@ -415,6 +746,85 @@ def test_refiner_training_info_uses_readable_sections(tmp_path):
     assert "Category compact view:\n-" in training_info
 
 
+def test_refiner_v2_exposes_clip_and_conditioning_as_optional_inputs():
+    inputs = FunPackVideoRefinerV2.INPUT_TYPES()
+
+    assert "clip" not in inputs["required"]
+    assert "positive_conditioning" not in inputs["required"]
+    assert "clip" in inputs["optional"]
+    assert "positive_conditioning" in inputs["optional"]
+
+
+def test_refiner_v2_accepts_conditioning_without_clip_and_loads_gemma3_tokenizer(tmp_path, monkeypatch):
+    refiner = FunPackVideoRefinerV2()
+    state_path = tmp_path / "state.json"
+    refiner._v2_state_path = lambda refinement_key: str(state_path)
+    tokenizer_modes = []
+
+    class FakeTokenizer:
+        name_or_path = "DreamFast/gemma-3-12b-it-heretic-v2"
+
+    def fake_get_tokenizer(mode="ltx2"):
+        tokenizer_modes.append(mode)
+        return FakeTokenizer()
+
+    monkeypatch.setattr(refiner, "_get_tokenizer", fake_get_tokenizer)
+    positive_conditioning = [(torch.full((1, 4, 3), 2.0), {"pooled_output": torch.ones(1, 3)})]
+
+    modified, status, training_info, _, negative = refiner.refine_v2(
+        "woman walking through neon rain",
+        None,
+        "Perfect",
+        "conditioning-input-test",
+        positive_conditioning=positive_conditioning,
+    )
+
+    assert tokenizer_modes == ["ltx2"]
+    assert "CONDITIONING-owned" in status
+    assert "Gemma3 tokenizer loaded: DreamFast/gemma-3-12b-it-heretic-v2" in training_info
+    assert modified[0][0].shape == positive_conditioning[0][0].shape
+    assert negative == []
+
+
+def test_refiner_v2_prefers_clip_when_both_clip_and_conditioning_are_connected(tmp_path, monkeypatch):
+    refiner = FunPackVideoRefinerV2()
+    state_path = tmp_path / "state.json"
+    refiner._v2_state_path = lambda refinement_key: str(state_path)
+    monkeypatch.setattr(refiner, "_get_tokenizer", lambda mode="ltx2": (_ for _ in ()).throw(AssertionError("unexpected tokenizer load")))
+    positive_conditioning = [(torch.full((1, 4, 3), 9.0), {"pooled_output": torch.ones(1, 3)})]
+
+    modified, status, training_info, _, negative = refiner.refine_v2(
+        "woman walking through neon rain",
+        FakeClip(),
+        "Perfect",
+        "clip-priority-test",
+        positive_conditioning=positive_conditioning,
+    )
+
+    assert "CLIP-owned" in status
+    assert "accepted connected positive CONDITIONING" not in training_info
+    assert torch.allclose(modified[0][0], torch.ones(1, 4, 3))
+    assert negative == []
+
+
+def test_refiner_v2_errors_without_clip_or_conditioning(tmp_path):
+    refiner = FunPackVideoRefinerV2()
+    state_path = tmp_path / "state.json"
+    refiner._v2_state_path = lambda refinement_key: str(state_path)
+
+    modified, status, training_info, _, negative = refiner.refine_v2(
+        "woman walking through neon rain",
+        None,
+        "Perfect",
+        "missing-conditioning-test",
+    )
+
+    assert modified == []
+    assert negative == []
+    assert "ERROR: V2 could not prepare conditioning" in status
+    assert "CLIP missing and no positive CONDITIONING connected" in training_info
+
+
 def test_prompt_enhancer_refusal_is_not_stored_as_last_run(tmp_path):
     refiner = FunPackVideoRefinerV2()
     state_path = tmp_path / "state.json"
@@ -494,6 +904,7 @@ def test_normal_previous_run_can_train_before_current_refusal_is_discarded(tmp_p
 def test_liked_action_detail_context_clusters_repair_missing_axes():
     refiner = FunPackVideoRefinerV2()
     global_state = {"phrase_memory": {}, "preferred_context_memory": {}}
+    rich_prompt = "woman walking reaching hand tiny particles rain reflections"
     liked_phrases = refiner._v2_classify_phrases(
         None,
         prompt_items(refiner, [
@@ -510,11 +921,18 @@ def test_liked_action_detail_context_clusters_repair_missing_axes():
 
     refiner._v2_update_phrase_memory(
         global_state,
-        {"prompt": "woman walking reaching hand tiny particles rain reflections", "phrases": liked_phrases},
+        {"prompt": rich_prompt, "phrases": liked_phrases},
         profile,
         1,
         feedback,
     )
+    assert "Preferred context stored" in refiner._v2_update_preferred_context_memory(
+        global_state,
+        {"phrases": liked_phrases},
+        profile,
+        2,
+        feedback,
+    )
 
     missing_profile = normalize_refiner_v2_rating("Missing details + action")
     missing_feedback = refiner._v2_axis_feedback(missing_profile, None)
@@ -523,6 +941,11 @@ def test_liked_action_detail_context_clusters_repair_missing_axes():
         prompt_items(refiner, ["woman", "rain"]),
         global_state,
     )
+    intent_phrases = refiner._v2_classify_phrases(
+        None,
+        refiner._ordered_prompt_phrases(rich_prompt),
+        global_state,
+    )
 
     repaired, status, candidates = refiner._v2_repair_prompt_for_missing_axes(
         "woman, rain",
@@ -530,21 +953,206 @@ def test_liked_action_detail_context_clusters_repair_missing_axes():
         global_state,
         None,
         missing_feedback,
+        intent_phrases=intent_phrases,
     )
 
-    assert "Preferred context stored" in refiner._v2_update_preferred_context_memory(
-        global_state,
-        {"phrases": liked_phrases},
-        profile,
-        2,
-        feedback,
-    )
     assert "walking" in repaired
     assert "tiny particles" in repaired
-    assert "preferred_context" in status
+    assert "intent" in status or "preferred_context" in status
     assert len(candidates) >= 2
 
 
+def test_prompt_repair_does_not_pull_unrequested_memory_for_any_missing_axis():
+    refiner = FunPackVideoRefinerV2()
+    global_state = {
+        "phrase_memory": {
+            "walking": {
+                "text": "walking",
+                "primary": "action",
+                "effective_category_scores": refiner._v2_heuristic_scores("walking"),
+                "wanted_axes": {"action": 5},
+                "score": 5.0,
+                "liked_count": 5,
+            },
+            "tiny particles": {
+                "text": "tiny particles",
+                "primary": "details",
+                "effective_category_scores": refiner._v2_heuristic_scores("tiny particles"),
+                "wanted_axes": {"details": 5},
+                "score": 5.0,
+                "liked_count": 5,
+            },
+            "cinematic lighting": {
+                "text": "cinematic lighting",
+                "primary": "style",
+                "effective_category_scores": refiner._v2_heuristic_scores("cinematic lighting"),
+                "wanted_axes": {"quality": 5},
+                "score": 5.0,
+                "liked_count": 5,
+            },
+            "glass reflections": {
+                "text": "glass reflections",
+                "primary": "details",
+                "effective_category_scores": refiner._v2_heuristic_scores("glass reflections"),
+                "wanted_axes": {"details": 2},
+                "score": 2.0,
+                "liked_count": 1,
+            },
+        },
+    }
+    profile = normalize_refiner_v2_rating("Awful")
+    feedback = refiner._v2_axis_feedback(profile, None)
+    current_phrases = refiner._v2_classify_phrases(
+        None,
+        prompt_items(refiner, ["woman", "glass"]),
+        global_state,
+    )
+
+    repaired, _, candidates = refiner._v2_repair_prompt_for_missing_axes(
+        "woman, glass",
+        current_phrases,
+        global_state,
+        None,
+        feedback,
+    )
+
+    candidate_texts = {candidate["text"] for candidate in candidates}
+    assert "glass reflections" in repaired
+    assert "walking" not in repaired
+    assert "tiny particles" not in repaired
+    assert "cinematic lighting" not in repaired
+    assert "walking" not in candidate_texts
+    assert "tiny particles" not in candidate_texts
+    assert "cinematic lighting" not in candidate_texts
+
+
+def test_prompt_repair_treats_same_word_with_different_neighbours_as_different():
+    refiner = FunPackVideoRefinerV2()
+    global_state = {
+        "phrase_memory": {
+            "turning head": {
+                "text": "turning head",
+                "primary": "action",
+                "effective_category_scores": refiner._v2_heuristic_scores("turning head"),
+                "wanted_axes": {"action": 4},
+                "score": 4.0,
+                "liked_count": 4,
+                "context_senses": {
+                    "mid|eyes,portrait": {
+                        "context": {
+                            "anchor_words": ["head", "turning"],
+                            "context_words": ["portrait", "eyes"],
+                            "position_bucket": "mid",
+                            "window": 3,
+                        },
+                        "category_weights": refiner._v2_category_template(0.0),
+                        "effective_category_scores": refiner._v2_heuristic_scores("turning head"),
+                        "category_evidence_count": 4,
+                        "occurrence_count": 4,
+                    },
+                },
+            },
+        },
+    }
+    profile = normalize_refiner_v2_rating("Missing action")
+    feedback = refiner._v2_axis_feedback(profile, None)
+    current_phrases = refiner._v2_classify_phrases(
+        None,
+        prompt_items(refiner, ["car", "turning wheel", "street"]),
+        global_state,
+    )
+
+    repaired, _, candidates = refiner._v2_repair_prompt_for_missing_axes(
+        "car, turning wheel, street",
+        current_phrases,
+        global_state,
+        None,
+        feedback,
+    )
+
+    assert "turning head" not in repaired
+    assert all(candidate["text"] != "turning head" for candidate in candidates)
+
+
+def test_vague_user_intent_lets_enhanced_positive_prompt_anchor_repair():
+    refiner = FunPackVideoRefinerV2()
+    global_state = {
+        "phrase_memory": {
+            "walking slowly": {
+                "text": "walking slowly",
+                "primary": "action",
+                "effective_category_scores": refiner._v2_heuristic_scores("walking slowly"),
+                "wanted_axes": {"action": 3},
+                "score": 3.0,
+                "liked_count": 3,
+            },
+        },
+    }
+    assert refiner._v2_user_intent_prompt_is_vague("Figure it out")
+    assert not refiner._v2_user_intent_prompt_is_vague("person walking")
+
+    profile = normalize_refiner_v2_rating("Missing action")
+    feedback = refiner._v2_axis_feedback(profile, None)
+    current_phrases = refiner._v2_classify_phrases(
+        None,
+        prompt_items(refiner, ["woman", "walking through glass hallway"]),
+        global_state,
+    )
+
+    repaired, _, candidates = refiner._v2_repair_prompt_for_missing_axes(
+        "woman, walking through glass hallway",
+        current_phrases,
+        global_state,
+        None,
+        feedback,
+        intent_phrases=[],
+    )
+
+    assert "walking slowly" in repaired
+    assert any(candidate["text"] == "walking slowly" for candidate in candidates)
+
+
+def test_complex_user_intent_ranks_before_matching_preferred_memory():
+    refiner = FunPackVideoRefinerV2()
+    global_state = {
+        "phrase_memory": {},
+        "preferred_context_memory": {
+            "reach-memory": {
+                "anchor": "reaching hand slowly",
+                "axes": {"action": 4},
+                "context": {},
+                "phrases": ["reaching hand slowly"],
+                "score": 10.0,
+                "liked_count": 8,
+            },
+        },
+    }
+    profile = normalize_refiner_v2_rating("Missing action")
+    feedback = refiner._v2_axis_feedback(profile, None)
+    current_phrases = refiner._v2_classify_phrases(
+        None,
+        prompt_items(refiner, ["woman"]),
+        global_state,
+    )
+    intent_phrases = refiner._v2_classify_phrases(
+        None,
+        refiner._ordered_prompt_phrases("woman reaching hand toward glass"),
+        global_state,
+    )
+
+    repaired, _, candidates = refiner._v2_repair_prompt_for_missing_axes(
+        "woman",
+        current_phrases,
+        global_state,
+        None,
+        feedback,
+        intent_phrases=intent_phrases,
+    )
+
+    assert "reaching hand toward glass" in repaired
+    assert candidates[0]["source"] == "intent"
+
+
 def test_phrase_clusters_train_more_strongly_than_ngrams_and_tokens():
     refiner = FunPackVideoRefinerV2()
     global_state = {"phrase_memory": {}, "preferred_context_memory": {}}
@@ -579,7 +1187,13 @@ def test_repair_candidates_saved_as_json_lists(tmp_path):
 
     refiner.refine_v2(rich_prompt, FakeClip(), "Perfect", "json-repair-test")
     refiner.refine_v2(rich_prompt, FakeClip(), "Perfect", "json-repair-test")
-    refiner.refine_v2("woman, rain", FakeClip(), "Missing details + action", "json-repair-test")
+    refiner.refine_v2(
+        "woman, rain",
+        FakeClip(),
+        "Missing details + action",
+        "json-repair-test",
+        user_intent_prompt=rich_prompt,
+    )
 
     state = json.loads(state_path.read_text(encoding="utf-8"))
     candidates = state["last_run"]["repair_candidates"]

web/funpack_refinement_key_loader.js

@@ -0,0 +1,250 @@
+import { app } from "../../scripts/app.js";
+import { api } from "../../scripts/api.js";
+
+const NODE_NAME = "FunPackRefinementKeyLoader";
+const NONE_KEY = "-None-";
+const BUTTON_NAMES = new Set([
+  "funpack_refinement_key_export",
+  "funpack_refinement_key_import",
+  "funpack_refinement_key_refresh",
+]);
+
+let cachedKeys = [NONE_KEY];
+const trackedNodes = new Set();
+let pendingRefresh = null;
+
+function widgetByName(node, name) {
+  return (node.widgets || []).find((widget) => widget.name === name);
+}
+
+function keyWidget(node) {
+  return widgetByName(node, "refinement_key");
+}
+
+function keyNameWidget(node) {
+  return widgetByName(node, "key_name");
+}
+
+function selectedKey(node) {
+  const selected = String(keyWidget(node)?.value || "").trim();
+  if (selected && selected !== NONE_KEY) {
+    return selected;
+  }
+  return String(keyNameWidget(node)?.value || "").trim();
+}
+
+function fitString(ctx, text, maxWidth) {
+  text = String(text ?? "");
+  if (ctx.measureText(text).width <= maxWidth) {
+    return text;
+  }
+  const ellipsis = "...";
+  let low = 0;
+  let high = text.length;
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    if (ctx.measureText(text.slice(0, mid) + ellipsis).width <= maxWidth) {
+      low = mid;
+    } else {
+      high = mid - 1;
+    }
+  }
+  return text.slice(0, low) + ellipsis;
+}
+
+function updateKeyWidget(node, values = cachedKeys) {
+  const widget = keyWidget(node);
+  if (!widget) {
+    return;
+  }
+  const current = widget.value;
+  const nextValues = current && !values.includes(current) ? [...values, current] : values;
+  if (widget.options) {
+    widget.options.values = nextValues;
+  }
+  if (!widget.value || !nextValues.includes(widget.value)) {
+    widget.value = nextValues[0] || NONE_KEY;
+  }
+}
+
+async function fetchKeys() {
+  try {
+    const response = await api.fetchApi(`/funpack/refinement_keys?cache_bust=${Date.now()}`, {
+      cache: "no-store",
+    });
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`);
+    }
+    const data = await response.json();
+    const values = Array.isArray(data.keys) && data.keys.length ? data.keys : [NONE_KEY];
+    cachedKeys = values;
+    return values;
+  } catch (error) {
+    console.warn("FunPack: failed to refresh refinement keys", error);
+    return cachedKeys;
+  }
+}
+
+async function refreshNode(node) {
+  const values = await fetchKeys();
+  updateKeyWidget(node, values);
+  node.setDirtyCanvas(true, true);
+}
+
+async function refreshTrackedNodes() {
+  if (pendingRefresh) {
+    return pendingRefresh;
+  }
+  pendingRefresh = (async () => {
+    const values = await fetchKeys();
+    for (const node of [...trackedNodes]) {
+      if (!node?.graph) {
+        trackedNodes.delete(node);
+        continue;
+      }
+      updateKeyWidget(node, values);
+      node.setDirtyCanvas(true, true);
+    }
+  })().finally(() => {
+    pendingRefresh = null;
+  });
+  return pendingRefresh;
+}
+
+async function exportKey(node) {
+  const key = selectedKey(node);
+  if (!key) {
+    app.canvas?.prompt?.("Refinement key export skipped", "Select or type a refinement key first.", () => {});
+    return;
+  }
+  const response = await api.fetchApi(`/funpack/refinement_keys/export?key=${encodeURIComponent(key)}&cache_bust=${Date.now()}`, {
+    cache: "no-store",
+  });
+  if (!response.ok) {
+    const error = await response.json().catch(() => ({}));
+    throw new Error(error.error || `Export failed with HTTP ${response.status}`);
+  }
+  const blob = await response.blob();
+  const url = URL.createObjectURL(blob);
+  const link = document.createElement("a");
+  link.href = url;
+  link.download = `funpack_refinement_${key}.json`;
+  document.body.appendChild(link);
+  link.click();
+  link.remove();
+  URL.revokeObjectURL(url);
+}
+
+function importKey() {
+  const input = document.createElement("input");
+  input.type = "file";
+  input.accept = ".json,application/json";
+  input.onchange = async () => {
+    const file = input.files?.[0];
+    if (!file) {
+      return;
+    }
+    try {
+      const data = JSON.parse(await file.text());
+      const response = await api.fetchApi("/funpack/refinement_keys/import", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(data),
+      });
+      if (!response.ok) {
+        const error = await response.json().catch(() => ({}));
+        throw new Error(error.error || `Import failed with HTTP ${response.status}`);
+      }
+      await refreshTrackedNodes();
+    } catch (error) {
+      console.warn("FunPack: refinement key import failed", error);
+      app.canvas?.prompt?.("Refinement key import failed", error.message || String(error), () => {});
+    }
+  };
+  input.click();
+}
+
+class FunPackRefinementKeyButton {
+  constructor(name, label, callback) {
+    this.name = name;
+    this.type = "custom";
+    this.options = { serialize: false };
+    this.value = "";
+    this.label = label;
+    this.callback = callback;
+  }
+
+  computeSize(width) {
+    return [width, LiteGraph.NODE_WIDGET_HEIGHT + 2];
+  }
+
+  draw(ctx, _node, width, y, height) {
+    const x = 20;
+    const w = width - 40;
+    const h = height - 2;
+    ctx.save();
+    ctx.beginPath();
+    ctx.roundRect(x, y + 1, w, h, [3]);
+    ctx.fillStyle = LiteGraph.WIDGET_BGCOLOR;
+    ctx.strokeStyle = LiteGraph.WIDGET_OUTLINE_COLOR;
+    ctx.fill();
+    ctx.stroke();
+    ctx.fillStyle = LiteGraph.WIDGET_TEXT_COLOR;
+    ctx.textAlign = "center";
+    ctx.textBaseline = "middle";
+    ctx.fillText(fitString(ctx, this.label, w - 12), width / 2, y + height / 2);
+    ctx.restore();
+  }
+
+  mouse(event, _pos, node) {
+    if (event.type === "pointerup") {
+      this.callback(node);
+      return true;
+    }
+    return event.type === "pointerdown";
+  }
+}
+
+function removeButtons(node) {
+  node.widgets = (node.widgets || []).filter((widget) => !BUTTON_NAMES.has(widget.name));
+}
+
+function addButtons(node) {
+  removeButtons(node);
+  const buttons = [
+    new FunPackRefinementKeyButton("funpack_refinement_key_export", "Export", (currentNode) => void exportKey(currentNode)),
+    new FunPackRefinementKeyButton("funpack_refinement_key_import", "Import", () => importKey()),
+    new FunPackRefinementKeyButton("funpack_refinement_key_refresh", "Refresh", (currentNode) => void refreshNode(currentNode)),
+  ];
+  for (const button of buttons) {
+    node.addCustomWidget(button);
+  }
+}
+
+function setupNode(node) {
+  trackedNodes.add(node);
+  updateKeyWidget(node);
+  addButtons(node);
+  void refreshNode(node);
+}
+
+app.registerExtension({
+  name: "funpack.refinementKeyLoader",
+  beforeRegisterNodeDef(nodeType, nodeData) {
+    if (nodeData.name !== NODE_NAME) {
+      return;
+    }
+
+    const originalOnNodeCreated = nodeType.prototype.onNodeCreated;
+    nodeType.prototype.onNodeCreated = function () {
+      originalOnNodeCreated?.apply(this, arguments);
+      setupNode(this);
+    };
+
+    const originalConfigure = nodeType.prototype.configure;
+    nodeType.prototype.configure = function (info) {
+      originalConfigure?.apply(this, arguments);
+      setupNode(this, info);
+    };
+  },
+});