# End-to-end verification runbook

- **Lesson ID:** 08
- **Goal:** Check every step from Mac training to the SwiftUI top-label UI, label eval, and real-device profile.
- **Human lesson:** [08-end-to-end-checklist.html](08-end-to-end-checklist.html)

## Prerequisites

- All previous lesson files and a buildable Xcode target.
- A Mac with MPS or CPU and a real device for profiling.

## Inputs, outputs, and artifacts

- **Inputs:** Fashion-MNIST, `clothing.pt`, `clothing.aimodel`, Xcode app, bundled sample, real device.
- **Outputs:** A signed-off run from training through label and performance evidence.
- **Artifacts:** Checked weights/asset, model-viewer record, app build, sample prediction, Instruments trace.

## Agent build steps

1. Train `ClothingCNN` on MPS if available or CPU otherwise; save CPU `clothing.pt`; verify a test sample.
2. Assert float32 NCHW `[1,1,28,28]` input in 0–1 and `[1,10]` logits in the fixed ten-class order.
3. Export with `torch.export.export`; run `run_decompositions(get_decomp_table())` before `to_coreai()`.
4. Convert with names `image` and `logits`, call `optimize()`, save `clothing.aimodel`, and inspect it.
5. Install Metal Toolchain, add the asset, load `AIModel`/`main`, and run one zero/sample NDArray.
6. Prepare once in app setup; resize/grayscale/scale a bundled sample and picked photo; run and display top label/confidence.
7. Use Core AI Debugger/gauge, then Core AI Instruments on real hardware. Tell first setup apart from later inference.
8. Run lesson 07: held-out accuracy and confusion matrix, open-coded mistakes, Mac versus Core AI JSONL, yes/no top-label-acceptable rule.
9. If anything fails, inspect names/shapes/types first, then decomposition order, build phases/toolchain, and image-prep match.

## Constraints

Mac MPS/CPU only; no CUDA. Use Core AI, not Core ML. Keep `clothing.pt` and `clothing.aimodel`. Contract: `image` `[1,1,28,28]` float32 0–1 → `logits` `[1,10]`; keep class order and prepare once. Check exact new SDK names against the installed Xcode 27 docs.

## Key concepts

- The runbook covers Mac training, conversion, SwiftUI label, profile, and label eval.
- The contract stays locked: `ToTensor()`, `image` `[1, 1, 28, 28]` float32 0-1, `logits` `[1, 10]`, function `main`.
- Both `clothing.pt` and `clothing.aimodel` must exist and match the model viewer.
- Triage order: model viewer names and shapes, then decomposition, toolchain, then image prep.

## Takeaways

- Done when a bundled sample shows a label, the picker uses the same path, and prepare runs once.
- Lesson 07 notes ship with the project: matrix, open codes, JSONL parity, yes or no rule.
- You now own the full path from Fashion-MNIST to a top label in SwiftUI.

## Acceptance checks

- [ ] `clothing.pt` loads and test inference returns ten finite logits.
- [ ] `clothing.aimodel` exists; viewer confirms `main`, `image`, `logits`, shapes, and types.
- [ ] Xcode builds with Metal Toolchain and asset in the target.
- [ ] Bundled sample produces a SwiftUI top label; picker follows the same path.
- [ ] No repeated model preparation occurs on picks.
- [ ] Real-device gauge and Core AI Instruments trace cover first and later runs.
- [ ] Lesson 07 accuracy, confusion matrix, open codes, and Mac versus Core AI JSONL exist.
- [ ] All constraints and artifacts are recorded before shipping.

## Environment setup

Use macOS with Python 3.11+ and `uv`:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
mkdir -p clothing-coreai && cd clothing-coreai
uv init --python 3.11
uv venv
uv add torch torchvision coreai-torch
uv run python -c "import torch, torchvision; print(torch.__version__, torchvision.__version__); print('MPS:', torch.backends.mps.is_available())"
uv run python train.py
```

Run lesson scripts with `uv run`. Prefer MPS on Apple silicon. Use CPU if MPS is missing. Do not add CUDA.