Add model card: naming convention and checkpoint index

README.md

@@ -1,3 +1,78 @@
 ---
 license: mit
+library_name: transformers
+pipeline_tag: text-generation
+tags:
+- designcoder
+- ui-generation
+- front-end
+- html
+- css
+- javascript
+- code-generation
+- full-sft
 ---
+
+# DesignCoder
+
+Checkpoint collection for **DesignCoder**, a family of full-parameter SFT models for UI design
+research and end-to-end HTML/CSS/JavaScript implementation.
+
+Each subfolder in this repository is a self-contained, directly loadable checkpoint.
+
+## Naming convention
+
+```
+designcoder_{basemodel}_{size}_{optimizer}_bs{global_batch}[_ep{epochs}]_step{global_step}[_r{rerun}]
+```
+
+- `basemodel` / `size`: base model family and parameter scale
+- `optimizer`: `muon` or `adamw`
+- `bs`: global batch size (`per_device × grad_accum × world_size`)
+- `ep`: only present when epochs differ from the default 2
+- `step`: trainer `global_step` of the exported weights
+- `r`: rerun index, only present for repeated runs of an identical configuration
+
+## Checkpoints
+
+| Subfolder | Base model | Optimizer | LR | Global batch | Epochs | Step | Notes |
+|---|---|---|---|---|---|---|---|
+| `designcoder_qwen3.5_4b_muon_bs32_step1900` | Qwen3.5-4B | Muon | 1e-5 | 32 | 2 | 1900 | smallest release |
+| `designcoder_qwen3.5_9b_muon_bs16_step3800` | Qwen3.5-9B | Muon | 1e-5 | 16 | 2 | 3800 | optimizer ablation (Muon arm) |
+| `designcoder_qwen3.5_9b_adamw_bs16_step3800` | Qwen3.5-9B | AdamW | 2e-5 | 16 | 2 | 3800 | optimizer ablation (AdamW arm) |
+| `designcoder_qwen3.5_9b_adamw_bs16_ep20_step38000` | Qwen3.5-9B | AdamW | 2e-5 | 16 | 20 | 38000 | epoch-scaling ablation |
+| `designcoder_qwen3.6_27b_adamw_bs32_step1900` | Qwen3.6-27B | AdamW | 1e-5 | 32 | 2 | 1900 | largest release |
+| `designcoder_qwen3.6_27b_adamw_bs32_step1900_r2` | Qwen3.6-27B | AdamW | 1e-5 | 32 | 2 | 1900 | rerun of the 27B configuration |
+
+## Shared training setup
+
+- Objective: full-parameter supervised fine-tuning (no LoRA / adapters)
+- Dataset: `designcoder_sft_v2_train`, 41,287 ShareGPT-format records
+- Chat template: `qwen3_5` with thinking enabled
+- Context length: 32,768
+- Sequence packing: enabled, with neat packing (no cross-sample attention)
+- LR schedule: cosine, warmup ratio 0.1
+
+## Usage
+
+```python
+from transformers import AutoModelForCausalLM, AutoProcessor
+
+repo = "xingxm/DesignCoder"
+subfolder = "designcoder_qwen3.5_4b_muon_bs32_step1900"
+
+model = AutoModelForCausalLM.from_pretrained(repo, subfolder=subfolder, dtype="auto", device_map="auto")
+processor = AutoProcessor.from_pretrained(repo, subfolder=subfolder)
+```
+
+To download a single checkpoint only:
+
+```bash
+hf download xingxm/DesignCoder --include "designcoder_qwen3.5_4b_muon_bs32_step1900/*" --local-dir ./DesignCoder
+```
+
+## Provenance
+
+Each subfolder additionally ships `trainer_state.json` / `trainer_log.jsonl` (and
+`training_loss.png` where available) so that the loss curve and exact step schedule of the run
+can be recovered from the checkpoint itself.