docs: refresh docs and skills for refactored public API helpers (#337)

Updates outdated docs and agent skills to match the public-API + DRY
refactor shipped across the themed PRs.

## Changes
- **`build_from_gguf` import** — now a top-level export, so
`docs/api/build_from_gguf.md` and `docs/getting-started.md` use `from
mobius import build_from_gguf` instead of the internal
`mobius.integrations.gguf` path.
- **weight-name-alignment skill** — new *Shared helpers* section
documenting the `_weight_utils` rename helpers, including the new
`rename_weight_keys` and `vlm_vision_weights`, so future model work
reuses them instead of hand-written rename loops.
- **multimodal-models skill** — points at the shared `vlm_*` weight
helpers.
- **moe-models skill** — notes `Qwen35MoEBlock` now subclasses
`Qwen2MoELayer`, and fixes stale class file paths (`models/qwen.py` →
`models/qwen35.py`).

## Dependencies
Depends on the API PRs landing first (the helpers/exports documented
here only exist on those branches):
- #333 — `build_from_gguf` top-level export
- #334 — `rename_weight_keys`
- #336 — `vlm_vision_weights`

Docs-only; no code or tests affected.

---------

Signed-off-by: Justin Chu <11205048+justinchuby@users.noreply.github.com>
Co-authored-by: Justin Chu <11205048+justinchuby@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: justinchuby

.agents/skills/moe-models/SKILL.md

@@ -200,13 +200,18 @@ Qwen35MoEDecoderLayer
 
 | Class | File | Purpose |
 |-------|------|---------|
-| `Qwen35MoEBlock` | `models/qwen.py` | MoE block with routed + shared experts |
-| `Qwen35MoEDecoderLayer` | `models/qwen.py` | Hybrid attention + MoE FFN layer |
-| `Qwen35MoETextModel` | `models/qwen.py` | Stacks decoder layers with RoPE |
-| `Qwen35MoECausalLMModel` | `models/qwen.py` | Top-level causal LM model |
+| `Qwen35MoEBlock` | `models/qwen35.py` | MoE block with routed + shared experts (subclasses `Qwen2MoELayer`) |
+| `Qwen35MoEDecoderLayer` | `models/qwen35.py` | Hybrid attention + MoE FFN layer |
+| `Qwen35MoETextModel` | `models/qwen35.py` | Stacks decoder layers with RoPE |
+| `Qwen35MoECausalLMModel` | `models/qwen35.py` | Top-level causal LM model |
 
 ### MoE block (`Qwen35MoEBlock`)
 
+`Qwen35MoEBlock` is a thin subclass of `Qwen2MoELayer` (`models/moe.py`) —
+the routed + gated-shared-expert composition is op-for-op identical, so it
+reuses the parent `forward` rather than duplicating the routing loop. Only
+construction (config wiring) differs.
+
 - **TopKGate routing**: 256 experts, top-8 in the full model (configurable
   via `num_local_experts` / `num_experts_per_tok`)
 - **Expert MLPs**: Standard `MLP` (gate/up/down projections, SiLU activation),

.agents/skills/multimodal-models/SKILL.md

@@ -167,6 +167,11 @@ Multimodal HF models often prefix text weights differently. Implement
 | `language_model.model.layers.0.…` | `layers.0.…` |
 | `vision_tower.vision_model.encoder.…` | `vision_tower.encoder.…` |
 
+Prefer the shared helpers in `mobius._weight_utils` over hand-written loops:
+`vlm_decoder_weights` (strip + tie), `vlm_embedding_weights` (filter + strip),
+and `vlm_vision_weights` (vision-tower filter + `fc1/fc2`→`up_proj/down_proj`).
+See the `weight-name-alignment` skill for the full helper table.
+
 > Read `references/weight-mappings.md` when you need full weight mapping
 > tables, shape mismatch fixes, ClippableLinear weight conventions, or
 > per-layer embedding splitting details.

.agents/skills/weight-name-alignment/SKILL.md

@@ -378,6 +378,50 @@ shared transformer + per-layer Q/K/V/MLP low-rank adapters.
 
 4. **For non-eliminable renames**, keep them in `preprocess_weights`.
 
+## Shared helpers (use instead of hand-writing loops)
+
+`mobius._weight_utils` centralises the renames that *do* have to stay in
+`preprocess_weights`. Prefer these over a hand-written
+`for name, tensor in state_dict.items(): name = name.replace(...)` loop:
+
+| Helper | Use for |
+|--------|---------|
+| `rename_weight_keys(state_dict, [(old, new), ...])` | Pure substring key renames. Applies ordered, cascading `str.replace` to every key and **raises on key collision**. Returns a new dict (values shared). |
+| `rename_mlp_projections(name, old_up, old_down)` | Per-key MLP rename to canonical `up_proj`/`down_proj` (e.g. `fc_in`/`fc_out`, `c_fc`/`c_proj`). |
+| `split_fused_qkv` / `split_interleaved_qkv_weights` / `split_codegen_qkv` | Split fused/interleaved QKV projections. |
+| `split_gate_up_proj` | Split a fused `gate_up_proj` into `gate_proj` + `up_proj`. |
+| `tie_word_embeddings(state_dict)` | Ensure both `embed_tokens.weight` and `lm_head.weight` exist when `tie_word_embeddings=True`. |
+| `strip_prefix(state_dict, prefix)` | Drop a common key prefix. |
+| `vlm_decoder_weights` / `vlm_embedding_weights` / `vlm_vision_weights` | VLM sub-model weight extraction (decoder strip+tie, embedding filter+strip, vision-tower filter + `fc1/fc2`→`up_proj/down_proj`). |
+| `_rename_moe_expert_weights` (in `mobius.models.moe`, not `_weight_utils`) | MoE expert weight remapping across architectures. |
+
+Example — a pure-rename `preprocess_weights`:
+
+```python
+from mobius._weight_utils import rename_weight_keys
+
+def preprocess_weights(self, state_dict):
+    return super().preprocess_weights(
+        rename_weight_keys(
+            state_dict,
+            [
+                (".self_attn.dense.", ".self_attn.o_proj."),
+                (".mlp.fc1.", ".mlp.up_proj."),
+                (".mlp.fc2.", ".mlp.down_proj."),
+            ],
+        )
+    )
+```
+
+For VLM vision sub-models, prefer `vlm_vision_weights`:
+
+```python
+from mobius._weight_utils import vlm_vision_weights
+
+def preprocess_weights(self, state_dict):
+    return vlm_vision_weights(state_dict, ("vision_tower.", "multi_modal_projector."))
+```
+
 ## Non-consecutive index patterns (setattr fallback)
 
 When HF uses `nn.Sequential` with non-consecutive parameter indices AND the

docs/api/build_from_gguf.md

@@ -3,7 +3,7 @@
 Build an ONNX `ModelPackage` from a GGUF model file.
 
 ```python
-from mobius.integrations.gguf import build_from_gguf
+from mobius import build_from_gguf
 ```
 
 > **Note**: Requires the optional `gguf` package:
@@ -37,7 +37,7 @@ def build_from_gguf(
 ## Examples
 
 ```python
-from mobius.integrations.gguf import build_from_gguf
+from mobius import build_from_gguf
 
 # Basic conversion (dequantizes to float)
 pkg = build_from_gguf("llama-3.2-1b-q4_0.gguf")

docs/getting-started.md

@@ -99,7 +99,7 @@ pkg = build("facebook/wav2vec2-base")
 Convert a GGUF model (e.g. from llama.cpp) to ONNX:
 
 ```python
-from mobius.integrations.gguf import build_from_gguf
+from mobius import build_from_gguf
 
 pkg = build_from_gguf("path/to/model.gguf")
 pkg.save("output/model/")