diff --git a/mockups/HTML_FILES.md b/mockups/HTML_FILES.md
new file mode 100644
index 0000000..ced2c6f
--- /dev/null
+++ b/mockups/HTML_FILES.md
@@ -0,0 +1,56 @@
+# HTML mockup files — pending manual upload
+
+The 6 HTML mockup files referenced in [`README.md`](README.md) are currently held outside the repo because they exceed the size that can be efficiently transferred through the automated upload pipeline used to bootstrap this repository.
+
+The files exist locally at `/mnt/user-data/outputs/` (or wherever the design session staged them):
+
+| Source filename | Target filename in repo | Size |
+|---|---|---|
+| `index.html` | `mockups/index.html` | 228 KB · 5413 lines |
+| `blocao-transcript-forensics.html` | `mockups/transcript-forensics.html` | 46 KB |
+| `hai-lcars-forensics.html` | `mockups/forensics-only.html` | 43 KB |
+| `hai-lcars-frigate.html` | `mockups/frigate-config.html` | 37 KB |
+| `hai-lcars-gitops.html` | `mockups/gitops-only.html` | 31 KB |
+| `hai-lcars-router-ui.html` | `mockups/router-ui-original.html` | 31 KB |
+
+`mockups/palette-comparison.html` (17 KB) is already in the repo — see it as the example of what each of the above looks like once committed.
+
+## How to add them
+
+From a workstation with the source files available:
+
+```bash
+git clone https://git.blocaolabs.com/jlcm/wdmUI.git
+cd wdmUI
+
+cp /path/to/index.html                         mockups/index.html
+cp /path/to/blocao-transcript-forensics.html   mockups/transcript-forensics.html
+cp /path/to/hai-lcars-forensics.html           mockups/forensics-only.html
+cp /path/to/hai-lcars-frigate.html             mockups/frigate-config.html
+cp /path/to/hai-lcars-gitops.html              mockups/gitops-only.html
+cp /path/to/hai-lcars-router-ui.html           mockups/router-ui-original.html
+
+git add mockups/
+git commit -m "docs(mockups): add full HTML mockup set"
+git push origin main
+
+# After verifying everything is committed:
+git rm mockups/HTML_FILES.md
+git commit -m "docs(mockups): remove placeholder, mockups now in repo"
+git push origin main
+```
+
+## Why the files matter
+
+These are the source-of-truth visual prototypes for the entire Blocao operator console plus the audio transcript counterpart. They are referenced from:
+
+- `README.md` (root)
+- `mockups/README.md`
+- Multiple ADRs in `decisions/`
+- Documentation under `docs/03-design/`
+
+Until they are committed, anyone reading the repo will see the references but not be able to open the actual mockups.
+
+## After upload
+
+Once the files are in the repo, this `HTML_FILES.md` should be deleted.