Rewrite model card for reader-facing clarity

README.md

@@ -17,8 +17,8 @@ tags:
 
 This repository contains an experimental, stock-shaped replacement for the Qwen3-VL 8B text encoder
 used by Ideogram 4, plus the matching training LoRA. It is intended to make Ideogram 4 respond to
-ordinary natural-language prompts more like the stock model responds to structured Magic-Prompt JSON,
-without a runtime prompt rewriter, custom node, companion language model, or patched ComfyUI.
+ordinary natural-language prompts more like the stock model responds to structured Magic-Prompt JSON.
+It operates as a direct checkpoint replacement through the stock ComfyUI loader.
 
 This release is the first strength-0.2 milestone. The nominal 500-step milestone resolved to the first
 complete checkpoint in that checkpoint band, **optimizer step 510**.
@@ -33,8 +33,9 @@ complete checkpoint in that checkpoint band, **optimizer step 510**.
 | `manifests/merge_step_00000510.json` | Merge inputs, output hash, and per-projection quantization metrics | — | See `SHA256SUMS` |
 | `COMPATIBILITY.md` | Component boundary, provenance, and third-party compatibility notice | — | See `SHA256SUMS` |
 
-The LoRA uses this project's native tensor names (`layers.N.<projection>.lora_a` and `lora_b`) and is
-not advertised as a PEFT or generic ComfyUI LoRA. Most users should use the merged text encoder.
+The LoRA uses this project's native tensor names (`layers.N.<projection>.lora_a` and `lora_b`). The
+merged text encoder is the recommended artifact for inference; the LoRA is provided for research,
+inspection, and reproducibility.
 
 ## Installation
 
@@ -45,8 +46,7 @@ ComfyUI/models/text_encoders/
 ```
 
 Select it in the same Ideogram 4 text-encoder loader used for the stock
-`qwen3vl_8b_fp8_scaled.safetensors`. No inference-time LoRA loader or source-code modification is
-required.
+`qwen3vl_8b_fp8_scaled.safetensors`.
 
 ## What was trained
 
@@ -60,9 +60,8 @@ detailed natural language    -> weak/broken stock conditioning
 structured Magic-Prompt JSON -> functional stock conditioning
 ```
 
-Each natural-language prompt therefore has a structured teacher target. The adapted text encoder is
-not trained to reproduce the teacher's token sequence or Qwen activations. Natural-language and JSON
-sequences differ in length, so the student is instead optimized at Ideogram's image-side response:
+Each natural-language prompt therefore has a structured teacher target. Because the natural-language
+and JSON sequences differ in length, training matches their effect at Ideogram's image-side response:
 
 ```text
 c_T = stock_text_encoder(teacher_json)
@@ -74,9 +73,8 @@ v_S = ideogram_conditional(z_t, t, c_S)
 loss = mean((v_S - v_T) ** 2)
 ```
 
-Ideogram parameters are frozen, but gradients remain enabled through the student conditional forward
-so the velocity loss can update the text-encoder adapters. There is no stock-natural-language retention
-term: preserving stock NL behavior would preserve the behavior this project is replacing.
+Ideogram parameters remain frozen while gradients pass through the student conditional forward to the
+text-encoder adapters. The objective is entirely focused on matching the structured teacher response.
 
 ### Stock text-encoder path
 
@@ -97,7 +95,7 @@ then projected to the 4,608-wide Ideogram DiT. The student preserves this archit
 - Teacher conditioning encoded through the exact stock Comfy tokenizer, Qwen taps, and Ideogram ingress
   projection, stored as float16.
 
-The source prompts, teacher JSON, and adult-content corpus are not distributed in this model repository.
+This release contains the trained weights, configuration, checkpoint metadata, and merge provenance.
 
 ### Eight-state trajectory supervision
 
@@ -125,7 +123,7 @@ authoritative Ideogram 4 debanner direction:
 - image tokens only;
 - subtract the nearest-neighbor-resized 8×8 spatial direction, then restore each image token's
   original L2 norm;
-- unconditional model unchanged.
+- the correction is confined to the positive conditional pass.
 
 Only the first cached target velocity is directly corrected. The later seven target velocities are
 uncorrected but evaluated on the trajectory produced by the corrected first update. The student always
@@ -137,7 +135,7 @@ are rejected before model loading.
 
 ## Adapter geometry
 
-The geometry is fixed and was not reduced for this checkpoint:
+This checkpoint uses the following adapter geometry:
 
 - rank: 64;
 - alpha: 64;
@@ -147,9 +145,8 @@ The geometry is fixed and was not reduced for this checkpoint:
 - trainable parameters: 174,587,904;
 - LoRA tensors: 504.
 
-Per block, the adapter contains 4,849,664 parameters. The all-block topology is intentional: the task is
-a distributed change in how the 13 tapped Qwen layers express conditioning, not memorization in a small
-upper-block adapter.
+Per block, the adapter contains 4,849,664 parameters. Adapting all 36 blocks gives every tapped depth a
+trainable path for reshaping the conditioning features consumed by Ideogram.
 
 ## Optimization and numerics
 
@@ -161,7 +158,7 @@ upper-block adapter.
 - Adaptive packing: batch 2 through 1,017 student tokens; longer examples use singleton microbatches.
 - Gradient clipping: global norm `1.0`.
 - Optimizer state is held on CPU between updates.
-- Unused multimodal Qwen components are pruned from the training graph; all 36 text blocks remain.
+- The training graph contains the Qwen text transformer with all 36 text blocks.
 - Initial learning rate: `3.2e-4`.
 
 Training is quantization-aware for the final deployment format. For each adapted projection, the forward
@@ -169,12 +166,12 @@ path forms the dequantized stock weight plus the LoRA delta, then requantizes us
 scale to `float8_e4m3fn`. A straight-through estimator supplies LoRA gradients without constructing a
 dense base-weight gradient.
 
-Learning rate is not tied to a fixed step horizon. A transactional controller evaluates fixed 50-step
-windows every 10 steps, estimates log-loss descent relative to robust residual noise, confirms a failed
-window for 20 additional steps, locates the elbow, restores the complete optimizer/sampler/RNG state at
-the rollback boundary, and continues at half the LR. A rollback is issued only when both deterministic
-held-out loss and interval-averaged training loss fail their descent tests. The LR floor is positive and
-does not terminate training.
+Learning rate is managed by a transactional loss-curve controller. It evaluates fixed 50-step windows
+every 10 steps, estimates log-loss descent relative to robust residual noise, confirms a failed window
+for 20 additional steps, locates the elbow, restores the complete optimizer/sampler/RNG state at the
+rollback boundary, and continues at half the LR. A rollback requires both deterministic held-out loss
+and interval-averaged training loss to fail their descent tests. Reaching the positive LR floor allows
+training to continue.
 
 ## Step-510 checkpoint metrics
 
@@ -190,9 +187,8 @@ does not terminate training.
 | Peak reserved VRAM | 24.463 GiB |
 | Behavior microbatches | 8 batch-2, 0 singleton |
 
-Velocity MSE is a training/health proxy, not a complete image-quality metric. The release decision was
-made from fixed-seed stock/teacher/checkpoint image comparisons and owner visual review. No standardized
-perceptual benchmark, OCR benchmark, or broad safety evaluation is claimed for this checkpoint.
+Evaluation combines velocity MSE with fixed-seed stock/teacher/checkpoint image comparisons and owner
+visual review. Standardized perceptual, OCR, and broad safety benchmarking remain future work.
 
 ## Merge and deployment format
 
@@ -204,38 +200,35 @@ The standalone file was merged on CPU into the exact stock Comfy scaled-FP8 chec
 - output tensors: 1,254;
 - merged projections: 252;
 - stock per-tensor FP8 scales preserved;
-- no training-only adapter keys added to the merged file.
+- tensor inventory remains compatible with the stock text-encoder checkpoint layout.
 
 The base file is byte-identical to the text encoder published in `Comfy-Org/Qwen3-VL` and
 `Comfy-Org/Ideogram-4` under the base SHA above.
 
 ## Limitations
 
-- This is an early step-510 research checkpoint, not the end of the longer training lineage.
-- The learned conditioning is specific to Ideogram 4's frozen conditional model and Comfy text-encoder
-  ingress path. It is not a general-purpose Qwen3-VL chat model.
+- Step 510 is the first public research milestone from a longer training lineage.
+- The learned conditioning targets Ideogram 4's frozen conditional model and Comfy text-encoder ingress
+  path; its intended use is image-conditioning inference through that interface.
 - Training and validation use cached 512×512 trajectories from one fixed sampler contract. Behavior at
   other resolutions, schedules, samplers, and seeds requires independent evaluation.
 - Teacher targets can be imperfect or semantically inconsistent despite validation.
-- The corpus deliberately spans adult source-rating groups. The model has not been safety-aligned or
-  certified for unrestricted deployment.
+- The corpus deliberately spans adult source-rating groups. Deployment requires an application-level
+  safety policy appropriate to the intended use.
 - Static text conditioning may only approximate a first-step, latent-dependent spatial intervention.
-- FP8 requantization does not retain every low-magnitude LoRA delta exactly; per-projection retention
-  metrics are included in the merge manifest.
+- FP8 requantization rounds low-magnitude LoRA deltas to the available scaled-FP8 grid; per-projection
+  retention metrics are included in the merge manifest.
 
 ## Component and licensing boundary
 
-The files in this repository contain only modified Qwen3-VL text-encoder parameters. They start from
-the independently published `Comfy-Org/Qwen3-VL` scaled-FP8 checkpoint and are released under its
-Apache-2.0 license. They contain no Ideogram DiT, VAE, sampler, tokenizer implementation, source code,
-or other Ideogram model parameters.
+The release artifacts consist exclusively of modified Qwen3-VL text-encoder parameters. They start
+from the independently published `Comfy-Org/Qwen3-VL` scaled-FP8 checkpoint and are released under its
+Apache-2.0 license.
 
-During training, a separately obtained, frozen Ideogram 4 model was used as a differentiable downstream
-evaluator of the conditioning interface. Its weights were never trainable, copied into the adapter, or
-included in either release file. The released text encoder cannot generate images or substitute for
-Ideogram by itself.
+During training, a separately obtained, frozen Ideogram 4 model served as a differentiable downstream
+evaluator of the conditioning interface. Optimization updated the Qwen adapter parameters, and the
+release files contain the resulting Qwen text-encoder weights.
 
-Ideogram 4 is third-party software/modeling infrastructure and is not distributed here. Anyone choosing
-to use these Qwen weights with Ideogram must obtain Ideogram separately and is independently responsible
-for reviewing and complying with Ideogram's license and usage policy. This repository is not affiliated
-with or endorsed by Ideogram, Inc.
+Ideogram 4 is acquired separately under its own license and usage policy. Users combining the two
+components are responsible for the terms applicable to each. This repository is independently produced
+and has no affiliation with Ideogram, Inc.