---
name: gdflash-progress-site
description: Update the GDFlash progress site (gdflash.research.makartkar.com) — add experiments or experiment sections to the Experiments page, edit the scheme diagrams, refresh the reading list, deploy. Use when asked to log a GDFlash experiment, add an experiment block/section, update the research progress site, or deploy site changes.
---

# GDFlash progress site

Published at https://gdflash.research.makartkar.com (nginx + Let's Encrypt on the
Hetzner server, ssh profile `hetzner` from `~/.ssh/config`).

Sources live in the **private GitHub repo `MakArtKar/research`** (local clone
`~/work/bayes_group/research`), folder `gdflash/`:

- `gdflash/site/` — deployable static site: `index.html`, `background.html`,
  `experiments.html`, `assets/` (styles, data files, renderers, diagram SVGs)
- `gdflash/diagrams/` — excalidraw generator scripts (`.mjs`), generated
  `.excalidraw` sources, exported `.svg`
- `gdflash/sync_reading_list.py` — refreshes the Notion reading list into
  `site/assets/reading-list-data.js` (needs `NOTION_TOKEN` env var or the
  gitignored `gdflash/site/.notion.env`)

**Deploy** (from the research repo root; `--delete` keeps the web root an exact mirror):

```bash
rsync -aq --delete gdflash/site/ hetzner:/var/www/gdflash.research.makartkar.com/ --exclude='.notion.env'
```

After deploying, commit and push the research repo.

**This skill is published on the site** at
https://gdflash.research.makartkar.com/skill.md so site-monitoring agents can
fetch it. After editing this file, copy it to `gdflash/site/skill.md` in the
research repo and deploy.

## Experiments page structure (`experiments.html`)

1. Three **base scheme diagrams**: GDFlash architecture / training / inference
   (`gdflash_{architecture,training,inference}.mjs` → `.svg`).
2. One **section per experiment block**, each consisting of:
   - `<h2>{Block name}</h2>` plus a short `<p class="note">` describing the recipe
   - `<details class="diagram-toggle">` holding three block-specialized diagrams
     (architecture / training / inference)
   - `<div class="exp-table" data-block="{block-id}"></div>` — the experiments
     table, rendered client-side by `assets/experiments.js`

The **experiments database** is `site/assets/experiments-data.js`
(`window.EXPERIMENTS_DB.experiments`). One record per experiment:

```js
{
  block: "tencdm-gdflash",            // section id (matches data-block)
  name: "TEncDM GDFlash baseline",
  description: "one line",
  status: "Not implemented",          // | "Waiting" | "In progress" | "Completed"
  wandb: "https://wandb.ai/...",      // or "" for none
  pr: "https://github.com/MakArtKar/SpecForge/pull/N",  // GitHub PR URL, or "" for none
  setup: "qwen3-8b-perfectblend",  // id from SETUPS_DB (renders as a link), or ""
  artifacts: { "cache": "s3://..." }, // dict label -> s3 path, {} for none
  features: { "Space": "Encodings (hiddens)", ... },  // Background-matrix choices
  details: "free-form comments / extra params"       // or "" (renders as Other details)
}
```

Feature names and choices should match the Background matrix
(`site/assets/background-data.js`).

## Add a new experiment (table row)

1. Append a record to `EXPERIMENTS_DB.experiments` with the `block` id of its section.
2. Deploy, commit, push. Nothing else — the table renders from the database.

## Add a new experiment section (block)

1. **Diagrams**: in `gdflash/diagrams/`, copy the three generators of the closest
   existing block (e.g. `tencdm_gdflash_*.mjs`) or the base `gdflash_*.mjs`;
   change the output filename and the title text; add the block-specific modules
   and arrows, highlighting them with a **bold purple border**
   (`strokeColor: "#6b21a8"`, `strokeWidth: 4`); where a legend exists, add a
   purple "{Block}-specific" row.
2. **Render and verify**: `node <generator>.mjs`, then export a PNG
   (`excalidraw-brute-export-cli -i X.excalidraw -o /tmp/x.png -f png -s 1 -b true`)
   and inspect it for overlaps/clipped labels before shipping. Then export the SVG
   (`-f svg -s 1 -b true`), **`chmod 644` the svg** (the exporter writes mode 0600
   and nginx returns 403 otherwise), and copy it to `gdflash/site/assets/`.
   LaTeX labels need local `latex` + `dvipng` (used by
   `excalidraw_diagram_helpers.mjs`).
3. **Page**: in `experiments.html`, duplicate the TEncDM GDFlash section (h2 +
   note + details with the three imgs + `exp-table` div) with the new block id
   and SVG names.
4. **Database**: seed at least one record with the new `block` id.
5. Deploy, commit, push.

## Conventions

- Diagram style: keep the base-diagram layout; all losses styled like L_diff
  (orange pills on orange paths); Frozen = blue, Trainable = red,
  block-specific = bold purple; prefix-derived stacks show 3 tokens.
- The base diagrams stay minimal — normalization / self-conditioning /
  time-conditioning and similar variations belong to per-block specialized
  diagrams, not the base scheme.

## Setups page (`setups.html`)

Data/eval configurations that make model comparisons fair (model-side
hyperparameters like lr/optimizer/schedule/block size are tuned per model and
are NOT part of a setup). Database: `site/assets/setups-data.js`
(`window.SETUPS_DB`) — `columns` fixes the table column order (Target model,
Train dataset, Train samples, Val dataset, Val samples, Max length, Benchmarks,
Seed); each setup is
`{id, name, status, params: {column: value}, artifacts: {label: path}}` —
`status` is "Not Processed" | "In Progress" | "Processed" (data preparation
state, rendered as a badge), and `artifacts` holds paths to data caches etc.,
rendered as its own trailing column.

- **Add a setup**: append a record to `SETUPS_DB.setups` (add a column to
  `columns` first if a new param is needed), deploy. Each row gets the anchor
  `setups.html#setup-{id}`; the anchored row is highlighted via `tr:target`.
- Experiments reference setups through their `setup` field; the Experiments
  table renders it as a link to that anchor (name resolved from SETUPS_DB —
  `experiments.html` loads `setups-data.js` for this).

## Agents page (`agents.html`)

Registry of automation agents that monitor the site (e.g. the hourly Dresden
experiment runner that launches Waiting experiments when a holder allocation is
free). Database: `site/assets/agents-data.js` (`window.AGENTS_DB.agents`) —
`{id, name, server, schedule, watches, action, status}` with status
"Active" | "Disabled" | "Planned". Keep this registry in sync with the real
state of the agents (flip status when an agent is armed or stopped).

## Other pages

- `background.html` — design-space feature matrix (defaults in
  `assets/background-data.js`; user edits live in browser localStorage) and the
  Notion-synced reading list (refresh with `python3 gdflash/sync_reading_list.py`,
  then deploy).