Model card and example images

.gitattributes

@@ -33,3 +33,11 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+fumika_0.jpg filter=lfs diff=lfs merge=lfs -text
+fumika_1.jpg filter=lfs diff=lfs merge=lfs -text
+fumika_2.jpg filter=lfs diff=lfs merge=lfs -text
+fumika_examples.jpg filter=lfs diff=lfs merge=lfs -text
+terra_0.jpg filter=lfs diff=lfs merge=lfs -text
+terra_1.jpg filter=lfs diff=lfs merge=lfs -text
+terra_2.jpg filter=lfs diff=lfs merge=lfs -text
+terra_examples.jpg filter=lfs diff=lfs merge=lfs -text

README.md

@@ -1,3 +1,74 @@
 ---
 license: apache-2.0
+base_model: OpenMOSS-Team/MOSS-Image-Base
+tags:
+  - lora
+  - moss-image
+  - character-reference
+  - image-editing
+  - anime
+library_name: comfyui
 ---
+
+# MOSS-Image CharRef v2
+
+A character-reference LoRA for **MOSS-Image Base**: give it one picture of a character as *Picture 1* and a prompt, and it draws
+that character – face, hair, outfit and art style – in a new scene. No per-character LoRA training needed.
+
+It works on single images and on whole comic pages (MOSS JSON page layouts with panels and speech bubbles). It is the
+"reference picture" option of the [Fumika](https://github.com/7err4/fumika) app.
+
+## Usage (ComfyUI ≥ 0.42)
+
+Needs the [ComfyUI-MOSS-Image-Ostris-Edit](https://github.com/ostris/ComfyUI-MOSS-Image-Ostris-Edit) node (reference latents +
+KV cache).
+
+1. `MOSSImageOstrisEditModelPatch` (kv_cache on) → `LoraLoaderModelOnly` with this LoRA at 1.0
+2. `TextEncodeMOSSImageOstrisEdit` with your reference as `image1` and a prompt that starts with
+   **`Same character and art style as Picture 1.`** followed by the scene (tags or sentences, or a MOSS JSON page layout)
+3. negative: the same encoder with an empty prompt
+4. 50 steps, cfg 3, euler / sgm_uniform, SkipLayerGuidance on single layer 22 (MOSS full mode)
+
+Tips:
+- A few appearance words in the prompt (hair style, eye colour, key outfit pieces) noticeably improve fidelity.
+- Outfits follow the reference unless the prompt names other clothing – so you can change outfits by text.
+- Clean, large references (full body or bust, plain background) work best.
+
+## Examples
+
+Reference (left) → three new scenes, CharRef v2 at 1.0, MOSS-Image full mode (50 steps, cfg 3, sgm_uniform, SLG single layer 22),
+832×1216, prompt = prefix + scene tags + appearance words. No cherry-picking: one seed per scene.
+
+![Fumika: library, rooftop at sunset, kitchen](fumika_examples.jpg)
+![Terra: library, rooftop at sunset, kitchen](terra_examples.jpg)
+
+## Training
+
+- ai-toolkit edit mode (`arch: moss_image`, `edit: true`, `kv_cache: true`), LoRA rank 32 / alpha 32, AdamW8bit 1e-4, batch 1,
+  1000 steps, 1024 px, MOSS-Image Base bf16.
+- ~1330 reference → target pairs: anime character art and synthetic renders of anime characters in many scenes, and renders of well-known adult anime
+  characters with mixed body types (2 references + 8 scenes each). Safe / suggestive only, no nudity; captions =
+  prefix + outfit / scene / pose tags, identity never named (it has to come from the picture).
+- Recipe idea from [pleiades7/MOSS-Image-CharRef-PoC](https://huggingface.co/pleiades7/MOSS-Image-CharRef-PoC) (v1 of this LoRA
+  showed inflated proportions; v2 rebalanced the data).
+
+## Limitations
+
+- Fine hair details (e.g. a single coloured streak, exact ponytail) can drift without appearance words in the prompt.
+- One reference per image: scenes with several characters only take the identity of *Picture 1* reliably.
+- Inherits MOSS-Image's limits (small text, hands).
+- Trained on anime art: photo and 3D styles survive, but a photorealistic / 3D face is not kept reliably (outfit and hair are,
+  the face drifts between scenes). Use it for anime / illustrated characters.
+- A reference cropped from a comic panel carries its props over (door, mug, even the speech bubble) – crop to the character.
+
+## Prohibited use
+
+Do not use this LoRA, alone or with other models, to:
+
+- create intimate or sexually explicit images of an identifiable real person without their explicit consent;
+- create child sexual abuse material or any sexual depiction of minors;
+- build or extend facial recognition databases by untargeted scraping of facial images;
+- manipulate people subliminally or deceptively in ways that cause them or others harm.
+
+These are prohibited practices under Art. 5 of the EU AI Act (as amended in 2026). If you publish a picture that resembles a
+real person, place or event and could pass as authentic (a deep fake), you must disclose that it is AI-generated (Art. 50(4)).