chore: publish safetensors NexaMat stack artifacts

README.md

@@ -1,36 +1,45 @@
 ---
-library_name: transformers
-pipeline_tag: text-generation
+library_name: pytorch
 tags:
 - materials-science
 - crystal-generation
 - diffusion
-- controller
-- nexamat
+- encoder
+- multimodal
+- gradio
+license: mit
 ---
 
-# NexaMat2
+# Nexa_Mat2
 
-NexaMat2 is the rollout artifact hub for the NexaMat stack. It is not a single monolithic model.
-It binds a frozen physics encoder, a constrained diffusion decoder, and a partially fine-tuned Qwen3-14B
-controller into one auditable materials-discovery workflow.
+`AethronPhantom/Nexa_Mat2` is the public artifact repository for the Nexa_Mat Gen Stack. It contains the frozen physics encoder, the constrained diffusion decoder, the experimental multimodal/controller pilot, and the stack manifest consumed by the public Space.
 
-## Current Controller
+Space: https://huggingface.co/spaces/AethronPhantom/nexamat-crystal-viewer
 
-```text
-model_id: AethronPhantom/Nexa_Mat2
-subfolder: multimodal/controller/nexa_mat_controller_fft_pilot_20260518T234148Z/final_model_merged
-base_model: Qwen/Qwen3-14B
-state: partial FFT pilot, not full-dataset FFT
-```
+## Artifacts
 
-## Stack Contract
+| Component | Path | Status |
+|---|---|---|
+| Encoder V1 | `encoder/v1/nexa_mat_V1_final.safetensors` | Frozen downstream handoff checkpoint. |
+| Encoder manifest | `encoder/v1/manifest.json` | Architecture, source URI, checksum, and training metadata. |
+| Diffusion V1 | `decoder/diffusion_v1/final_checkpoint.safetensors` | Production diffusion/checkpoint handoff for constrained sampling. |
+| Diffusion manifest | `decoder/diffusion_v1/manifest.json` | Architecture, eval, checksum, and operating-mode metadata. |
+| Controller pilot | `multimodal/controller/nexa_mat_controller_fft_pilot_20260518T234148Z/final_model_merged/model.safetensors` | Experimental Qwen-based controller pilot. |
+| Cross-attention contract | `cross_attention_contract.json` | Interface contract joining encoder, decoder, controller, evidence, and task-head lanes. |
+| Stack manifest | `stack_manifest.json` | Canonical manifest for the public Space and downstream tooling. |
 
-- Encoder: physics grounding and plausibility scoring.
-- Decoder: best-of-N constrained candidate proposal.
-- Controller: ranking, rejection, evidence routing, and explanation.
-- Cross-attention bridge: adapter surface for text, encoder, decoder, task, and evidence streams.
+## Intended Use
 
-See `stack_manifest.json` for the machine-readable rollout contract.
+The stack is intended for materials candidate triage. Forward mode proposes constrained candidate structures from a design intent. Reverse mode ranks a candidate pool against a target use case. Generated candidates should be treated as hypotheses for DFT and downstream validation, not as confirmed stable materials.
 
-Status: `rollout_partial_controller`.
+## Component Roles
+
+The encoder is the physics-grounding layer. It learned a periodic materials manifold from the Nexa_Mat V1 training surface and is frozen for downstream generative experiments.
+
+The diffusion decoder is the proposal layer. It repairs and proposes structures under constraints, but should be used as a best-of-N sampler with filtering instead of a one-shot oracle.
+
+The multimodal/controller layer is the semantic/evidence layer. It connects model outputs to use cases, evidence packets, explanations, and reverse-pool ranking. The published controller checkpoint is a pilot, not a final full fine-tune.
+
+## Limitations
+
+These artifacts do not replace DFT, relaxation, experimental validation, or synthesis review. The decoder is strongest in constrained sampling and weaker in unconditional high-yield generation. The controller should not be trusted for unsupported literature claims unless paired with an evidence retrieval layer.