# Presentation Archive Guidance

This archive contains talks, course material, posters, and recordings. Recent
talk projects are usually organized as `YEAR-topic/` with one or more dated or
venue-specific subfolders. Most full slide decks are reveal.js presentations,
commonly in `index.html`, `presentation.html`, or `presentation/index.html`.
Some folders are recordings-only or poster-only; document those honestly rather
than forcing them into the reveal.js pattern.

## Working in This Archive

- Keep projects self-contained. Copied assets, duplicated `custom.css` files,
  and local reveal.js/plugin/vendor trees are intentional.
- Do not centralize shared images, CSS, or reveal.js dependencies unless the
  user explicitly asks for a refactor.
- Prefer editing the deck and local assets in place. If a subfolder is a venue
  variant, keep its changes local to that subfolder.
- Read `HEADER.md` when present. These files often contain the public landing
  page summary, an embedded deck or recording, and links to related papers or
  packages.
- For quick deck inspection, use `tools/reveal_text.py`:

```bash
tools/reveal_text.py path/to/index.html --max-chars 20000
tools/reveal_text.py path/to/presentation.html --max-chars 20000
```

The helper is deliberately lossy. It strips styling and most tags while keeping
visible text, image labels, media labels, and simple slide delimiters.

## Lightweight HTML Linting

For hand-edited reveal.js decks, prefer a tiny structural sanity check over a
full HTML/style/accessibility validator. Generic validators are usually too
noisy for this archive because inline styles, missing `alt` text, autoplaying
local videos, reveal-specific attributes, and quick table markup are common and
intentional.

Use `tools/reveal_lint.py` to check only basic tag nesting and obvious stray or
unclosed tags:

```bash
tools/reveal_lint.py path/to/index.html
tools/reveal_lint.py path/to/presentation.html
```

For a compact archive-wide pass over the current talk decks, avoid vendored
HTML and cap the report:

```bash
find 2022-* 2023-* 2024-* 2025-* 2026-* -type f \
  \( -name 'index.html' -o -name 'presentation.html' \) \
  ! -path '*/three.js-r145/*' ! -path '*/MathJax/*' \
  ! -path '*/dist/*' ! -path '*/plugin/*' \
  ! -path '*/fontawesome-free-*/*' -print0 |
  xargs -0 tools/reveal_lint.py --max-problems 40
```

The linter prints `file:line:column: message` plus one summary line. Treat it as
a quick smoke test before or after editing a deck, not as a complete HTML
conformance check. If a stricter tool such as `tidy` is available, run it only
on the specific deck being edited and cap the output with `sed -n '1,120p'`.

## Reveal.js Style

The house style is direct, visual, and research-talk oriented. Decks usually use
the dark reveal theme with `custom.css`, local image/video assets, KaTeX math,
highlight.js, notes, markdown support, `hash: true`, and `slideNumber: true`.
Most decks initialize plugins like:

```js
plugins: [ RevealMarkdown, RevealHighlight, RevealNotes, RevealMath.KaTeX ]
```

Some talks add chalkboard support. Preserve optional plugins already present in
a deck instead of normalizing them away.

Slides often use nested `<section>` blocks: outer sections are major chapters
and inner sections are vertical slides. When adding or moving material, preserve
that navigation rhythm. Title slides are terse: title, Stefan Krastanov, UMass
or MIT affiliation, and venue/date.

Fragments are a primary pacing tool. Expect `class="fragment"`, directional
variants such as `fade-up`, `fade-left`, `fade-right`, `fade-in-then-out`, and
explicit `data-fragment-index` for staged overlays. Do not flatten fragments
unless asked; they are part of the delivery.

`data-auto-animate` is used heavily for incremental visual stories: Alice/Bob
entanglement, growing research overview grids, technology-stack reveals, and
successive code or figure overlays. Match existing `data-id` usage if extending
an animated sequence.

Interactive and media slides appear throughout. Examples include local
`.mp4`/`.webm` videos, iframes to demos, and `data-background-iframe` with
`data-background-interactive`. Keep these references local when they already
are local; only rely on remote URLs when the existing deck already does.

## Custom CSS Habits

Many newer decks carry nearly identical `custom.css` files. Common idioms:

- `.flex-h` creates horizontal flex layouts centered on the slide, usually with
  `max-width: 80%`, `gap: 1em`, and children with `flex-basis: 50%`.
- `figure` is used as the basic visual unit. Figures are inline blocks with
  small margins; images typically get a small border radius, a border based on
  `var(--r-main-color)`, `max-width: 100%`, and `box-sizing: border-box`.
- White or light-background figures often use inline `background-color:white`
  or padding directly on the image. This is normal for paper screenshots,
  plots, circuit diagrams, and logos on a dark theme.
- `.bib` is a fixed-position bibliography block in the lower-right corner,
  usually an ordered list of `li > address + cite + time`. It uses a custom
  counter style for compact reference marks, small font size, and inline
  author/title/year metadata.
- `.border` and `.border-bottom` are lightweight emphasis helpers for equations,
  small comparison boxes, and staged lists.
- `.bc0` through `.bc9` and `.c0` through `.c9` are categorical color helpers,
  often following a Tableau-like palette. They are used for technology-stack
  layers, labels, and compact highlights.
- Inline style attributes are common and acceptable in these decks. They often
  tune `max-width`, `font-size`, `margin`, absolute positioning, or slide-local
  figure scaling.

When adding CSS, prefer the local `custom.css` if a rule is reused in the deck.
For one-off positioning or venue-specific figure sizing, inline styles are
consistent with the archive.

## Recurring Content Patterns

Several slide patterns are reused across projects and venues:

- The quantum technology stack: Materials, Analog Control, Noisy Digital
  Circuits, Error Correction, Quantum Algorithms. This is often a chapter
  opener or framing slide.
- Research overview grids: room-temperature optical quantum computing,
  photonic neural networks, microwave control/networking, spin-mechanics,
  learning hardware parameters, networking, distillation, modular MBQC, and
  error correction.
- Tool-building slides: QuantumClifford.jl, QuantumSavory.jl, BPGates.jl,
  WaveguideQED.jl, Symbolics.jl, simulator backends, Clifford algebra,
  perturbative/weakly non-Clifford methods, and discrete-event network sims.
- Community/open-source slides: GitHub organization links, CQN references,
  open-source package ecosystems, bug bounties, mini dev grants, GSoC, and
  contributor/student project notes.
- Hiring and group-status slides: UMass Amherst/MIT opportunities, email
  contact, software engineering, quantum science, student names, and "where we
  are" group overview material.
- Entanglement pedagogy: Alice/Bob qubits, Bell states, noisy Bell pairs,
  color-center protocols, microwave transduction, purification circuits, and
  error propagation as detection.
- Summer-school/course material: practical Julia setup, Clifford formalism,
  state-vector simulation, tensor networks, discrete-event simulation,
  QuantumSavory, HPC, and quantum information course recordings.

## Project and Subfolder AGENTS.md Files

Each top-level `2022-*` through `2026-*` project folder should have a detailed
`AGENTS.md` describing what the folder contains, entry points, themes, and
editing caveats. Immediate subfolders that are actual talk variants should have
shorter `AGENTS.md` files with local specifics: venue/date, deck path, major
differences from sibling variants, and asset/vendor caveats.

Skip generated or vendored support directories such as `dist`, `plugin`,
`three.js-r145`, `MathJax`, `fontawesome-free-*`, `node_modules`, `.git`, and
`.vscode`. Those folders are dependencies or generated support material, not
separate projects.