DEPLOY.md

# Deploying this directory as a HuggingFace Space

This directory is a self-contained static HuggingFace Space ready to push. Total bundle size is ~124 MB (the bulk is the two 60K data packs at 61 MB each); the index.html + scripts + weights together are under 3 MB.

## One-time setup

You need: a HuggingFace account, the `huggingface_hub` Python CLI, and an HF write token.

```bash
pip install -U huggingface_hub
huggingface-cli login          # paste your token from https://huggingface.co/settings/tokens
```

Install Git LFS once (required for the 60 MB data packs):

```bash
brew install git-lfs           # macOS;  apt-get install git-lfs  on Linux
git lfs install
```

## Create the space and push

```bash
# 1. Create an empty static space named cortex-conv on huggingface.co/spaces/<your-username>/cortex-conv
huggingface-cli repo create cortex-conv --type space --space-sdk static

# 2. Clone the empty space repo somewhere
git clone https://huggingface.co/spaces/<your-username>/cortex-conv ~/cortex-conv-space

# 3. Mirror this directory into the clone
rsync -a --delete --exclude=.git /Users/exobit/developer/fnm-gpu/hf_space/  ~/cortex-conv-space/

# 4. Push (the .gitattributes file already routes the JSON packs to LFS)
cd ~/cortex-conv-space
git lfs track "*.json"
git add .gitattributes README.md index.html PAPER_COMPANION.md tests/ weights/ mnist/ fashion/
git commit -m "initial: cortex-conv ships pre-trained at 96.8% MNIST"
git push
```

The Space will build automatically (a static space is just a file server, no build step). Open `https://huggingface.co/spaces/<your-username>/cortex-conv` and the page should load at 96.8% MNIST test accuracy within ~3 seconds on first visit.

## Verifying the deployed space

Visit the Space URL with a Chrome/Edge/Safari browser that supports WebGPU. Within 3 seconds you should see:

- Test accuracy: **96.8%**
- Status label: `idle (cortex-conv · webgpu+pretrained · 34,106 params)`
- Equation header: `CORTEX-CONV (2-conv 16,16, γ=0.1, banked V1 mask, drive-clamp · 34,106 params) · CORTEX NEURON · ADAGO · MNIST`

If WebGPU is unavailable in the visitor's browser, the page falls back to a CPU-only path with the embedded 6K MNIST and runs much slower.

## Notes

- HuggingFace Spaces by default serve from CDN with proper MIME types for `.json` and `.js` — no extra config needed.
- The `sdk: static` line in `README.md` frontmatter is what tells HF this is a static site (not a Gradio or Streamlit app).
- Updates: after editing files in `/Users/exobit/developer/fnm-gpu/hf_space/`, repeat the `rsync` + `git add` + `git commit` + `git push` steps. HuggingFace re-deploys automatically on every push.
- To regenerate the bundled weights snapshot after architecture changes, run `tools/train_cortex_dump.cjs` from the project root (not from `hf_space/`), then copy the resulting `weights/cortex_conv_mnist_R28.json` into `hf_space/weights/`.