Release Notes — Format & Structure Guide

How to create and maintain release note pages in cavai-release-notes.

Repository Structure

cavai-release-notes/
├── index.html                  # Landing page — card grid for monthly + individual releases
├── shared/                     # CSS, images, logos shared across all pages
│   ├── style.css               # Main stylesheet (monthly overviews + landing page)
│   ├── release-page.css        # Individual release pages only
│   ├── bubbles.png             # Mascot image
│   ├── cavai-logo.svg          # Header logo
│   └── cavai-logo-white.png    # Footer logo
├── 2026-03/                    # Monthly overview — March 2026
│   ├── index.html
│   └── img-*.png               # Screenshots for feature cards
├── 2026-04/                    # Monthly overview — April 2026
├── releases/
│   ├── af-8.23.1/index.html    # Individual release — AF patch
│   ├── ce-6.8.5/index.html     # Individual release — CE patch
│   └── ...
└── cli/                        # CLI tool (deploy, generate, preview)

Deploy

bash

npm run deploy    # Deploys to Cloudflare Pages via wrangler

Deploys the entire working directory. All files (including untracked) are uploaded.

Page Types

1. Individual Release Page (`releases/<version>/index.html`)

One page per version bump. Uses shared/release-page.css.

Structure

html

<link rel="stylesheet" href="../../shared/style.css">
<link rel="stylesheet" href="../../shared/release-page.css">

<!-- Hero with version title and GitHub changelog link -->
<header class="hero">
  <h1 class="hero-title">Application Frontend 8.23.1</h1>
  <p class="hero-sub">April 23, 2026</p>
  <a class="hero-gh-link" href="https://github.com/Cavai/.../compare/v8.23.0...v8.23.1">Full changelog on GitHub →</a>
</header>

<main class="release-page">
  <!-- One section per type: Improvements, Bug Fixes, New Features -->
  <div class="release-section">
    <div class="release-section-label imp">Improvements</div>
    <div class="release-item">
      <!-- Content + meta -->
    </div>
  </div>
</main>

Group into two bolker (Improvements + Bug Fixes) instead of separate items:

html

<div class="release-item">
  <div class="release-item-body expanded" style="display:flex;flex-direction:column;gap:1.2em">
    <p><strong>Title</strong><br>Description paragraph.</p>
    <p><strong>Title</strong><br>Description paragraph.</p>
  </div>
  <div class="release-item-meta">
    <!-- Author, reviewer(s), PR link, date — listed ONCE -->
  </div>
</div>

Key points:

expanded class removes the fade/max-height (no "Read more" needed)
gap: 1.2em adds spacing between entries
Title on its own line via <br>, not inline with em-dash
Meta block appears once at the bottom

When items have different PRs

Use separate release-item blocks, each with its own meta:

html

<div class="release-item">
  <div class="release-item-title">Feature Title</div>
  <div class="release-item-body"><p>Description.</p></div>
  <button class="release-item-toggle">Read more ↓</button>
  <div class="release-item-meta"><!-- meta --></div>
</div>

The toggle button auto-hides if content fits without truncation (JS handles this).

Section label classes

Class	Label	Color
`imp`	Improvements	Orange accent
`fix`	Bug Fixes	Teal accent
`new`	New Features	Pink accent

2. Monthly Overview Page (`YYYY-MM/index.html`)

Published at end of month or start of next. Uses shared/style.css only (not release-page.css).

Structure

html

<link rel="stylesheet" href="../shared/style.css">

<!-- Hero -->
<header class="hero">
  <h1 class="hero-title">Release Notes</h1>
  <p class="hero-sub">What's new in the Cavai platform — features, fixes, and improvements.</p>
  <span class="hero-date">APRIL 2026</span>
  <div class="hero-versions" id="hero-filters">
    <!-- One pill per repo that has changes this month -->
    <span class="hero-version-pill" data-filter="AF" title="Application Frontend — ...">Frontend</span>
    <span class="hero-version-pill" data-filter="CE" title="Creative Engine — ...">Engine</span>
  </div>
</header>

<main class="page">
  <!-- Summary paragraph -->
  <div class="month-summary"><p>High-level month summary.</p></div>

  <!-- Highlights — feature cards -->
  <div class="section-head">Highlights</div>
  <div class="feature-card fade-in"><!-- ... --></div>

  <!-- Changelog — collapsible per-repo list (optional) -->
  <div class="section-head">Changelog</div>
  <div class="changelog-repo fade-in"><!-- ... --></div>
</main>

Filter pills

Only include repos that had changes. Available repo codes:

Code	Label	Description
`AF`	Frontend	Application Frontend
`CE`	Engine	Creative Engine
`AB`	Backend	Application Backend
`CC`	Composer	Creative Composer
`LP`	Logs Parser	Analytics pipeline
`MCP`	MCP	AI assistant tools
`AP`	Assets Proxy	CDN and API proxy
`DOCS`	Docs	Documentation
`SL`	Scripts	Script Library
`WEB`	Website	cavai.com

Feature card

html

<div class="feature-card fade-in">
  <div class="feature-header">
    <div class="feature-icon new">✨</div>         <!-- or imp: ⚙ -->
    <span class="feature-title">Animation System</span>
    <span class="feature-badge badge-feature">New Feature</span>
  </div>

  <p class="feature-lead">One-sentence summary.</p>

  <!-- Optional: subtitles and sub-sections -->
  <div class="feature-subtitle">Builder</div>
  <div class="feature-body"><p>Details.</p></div>

  <!-- Optional: images -->
  <div class="media-row">
    <img src="img-something.png" alt="Description">
  </div>
  <p class="media-caption">Caption text.</p>

  <!-- REQUIRED: Meta with author(s), reviewer(s), PR(s), date -->
  <div class="feature-meta">
    <!-- Author -->
    <span class="author-link" style="display:inline-flex;align-items:center">
      <span class="author-tooltip">NicolayKjarnet<br><strong>Author</strong></span>
      <img class="meta-avatar" src="https://github.com/NicolayKjarnet.png?size=32" alt="">
    </span>
    <a class="meta-name" href="https://github.com/NicolayKjarnet" target="_blank" rel="noopener">NicolayKjarnet</a>

    <!-- Reviewer(s) — ALWAYS include, use opacity:.45 -->
    <span class="author-link" style="display:inline-flex;align-items:center">
      <span class="author-tooltip">McSneaky<br><strong>Reviewer</strong></span>
      <img class="meta-avatar" src="https://github.com/McSneaky.png?size=32" alt="" style="opacity:.45">
    </span>
    <a class="meta-name" href="https://github.com/McSneaky" target="_blank" rel="noopener" style="opacity:.45">McSneaky</a>

    <span class="meta-dot">&middot;</span>

    <!-- PR link(s) with repo tooltip -->
    <a class="pr-link repo-link" href="https://github.com/Cavai/Application-Frontend/pull/1854" target="_blank" rel="noopener">
      <span class="repo-tooltip"><strong>APPLICATION FRONTEND</strong>Ad builder UI — configuration panels and management views</span>
      AF #1854
    </a>

    <span class="meta-date">Apr 22–23</span>
  </div>
</div>

Badge classes

Class	Text	Use for
`badge-feature`	New Feature	Brand new functionality
`badge-improvement`	Improvement	Enhancement to existing feature
`badge-fix`	Fixes	Bug fix or correction

Feature icon

Type	HTML	Meaning
`new`	`✨` (✨)	New feature
`imp`	`⚙` (⚙)	Improvement or fix

Meta Block — Required Fields

Every feature card and release item MUST include:

Author(s) — full opacity avatar + name
Reviewer(s) — opacity: .45 on avatar and name link. Check gh pr view <number> --repo Cavai/<repo> --json reviews --jq '.reviews[].author.login'
PR link(s) — with repo-link class and repo-tooltip containing repo name + description
Date range — <span class="meta-date">Apr 22–23</span>

Author HTML

html

<span class="author-link" style="display:inline-flex;align-items:center">
  <span class="author-tooltip">USERNAME<br><strong>Author</strong></span>
  <img class="meta-avatar" src="https://github.com/USERNAME.png?size=32" alt="">
</span>
<a class="meta-name" href="https://github.com/USERNAME" target="_blank" rel="noopener">USERNAME</a>

Reviewer HTML (same but dimmed)

html

<span class="author-link" style="display:inline-flex;align-items:center">
  <span class="author-tooltip">USERNAME<br><strong>Reviewer</strong></span>
  <img class="meta-avatar" src="https://github.com/USERNAME.png?size=32" alt="" style="opacity:.45">
</span>
<a class="meta-name" href="https://github.com/USERNAME" target="_blank" rel="noopener" style="opacity:.45">USERNAME</a>

Known contributors

GitHub username	Role
`NicolayKjarnet`	Developer
`McSneaky`	Developer (Kevin)
`haakonmydland`	Developer (Haakon)
`copilot-pull-request-reviewer`	GitHub Copilot (automated reviewer)

PR link HTML

html

<a class="pr-link repo-link" href="https://github.com/Cavai/REPO/pull/NUMBER" target="_blank" rel="noopener">
  <span class="repo-tooltip"><strong>REPO DISPLAY NAME</strong>Short description</span>
  CODE #NUMBER
</a>

Repo tooltip descriptions:

Code	Display name	Tooltip description
AF	APPLICATION FRONTEND	Ad builder UI — configuration panels and management views
CE	CREATIVE ENGINE	The runtime that displays and powers interactive creatives — handles all visual rendering, styling, animations, user flows, and analytics
CC	CREATIVE COMPOSER	Prepares creatives for delivery — optimizes fonts, compresses data, and packages everything the Engine needs to run the ad
AB	APPLICATION BACKEND	The server behind the platform — manages user accounts, campaigns, creatives, and connects to external services
MCP	CAVAI MCP SERVER	Lets AI assistants like Claude manage campaigns, pull reports, and work with creatives through natural language

Landing Page (`index.html`)

Monthly overview card

html

<!-- In #panel-monthly .release-grid -->
<a class="release-card fade-in" href="2026-04/">
  <div class="release-card-header">
    <span class="release-card-date">April 2026</span>
    <span class="release-card-version">Monthly</span>
  </div>
  <div class="release-card-body">
    One-sentence summary of the month.
  </div>
  <div class="release-card-highlights">
    <span class="release-highlight">Tag 1</span>
    <span class="release-highlight">Tag 2</span>
  </div>
  <span class="release-card-arrow">&rarr;</span>
</a>

Comment out with  until the month is complete.

Individual release card

html

<!-- In #panel-releases .release-grid, ordered newest first -->
<a class="release-card fade-in" data-repo="af" href="releases/af-8.23.1/">
  <div class="release-card-header">
    <span class="release-card-date">Frontend 8.23.1</span>
    <span class="release-card-version">Apr 23</span>
  </div>
  <div class="release-card-body">
    Short summary of what changed.
  </div>
  <div class="release-card-highlights">
    <span class="release-highlight">Tag</span>
  </div>
  <span class="release-card-arrow">&rarr;</span>
</a>

data-repo values: af, ce, ab — used by the filter buttons.

Checklist — New Individual Release

Create releases/<repo>-<version>/index.html
Add hero with version, date, GitHub changelog link
Group items by type (Improvements / Bug Fixes / New Features)
If all items share one PR → use grouped format (one body, one meta)
If items have different PRs → use separate items
Add reviewers — check with gh pr view
Add card to landing page index.html (newest first in grid)
Update monthly overview highlights if applicable
Commit, push, npm run deploy

Checklist — New Monthly Overview

Create YYYY-MM/index.html
Add hero with month, filter pills for relevant repos
Write month summary paragraph
Create feature cards for each major highlight
Add author + reviewer(s) to every feature card
Add screenshots to feature cards where useful (save as img-*.png in same folder)
Optionally add changelog section with collapsible per-repo items
Add monthly card to landing page (comment out until ready)
Uncomment card when month is complete
Commit, push, npm run deploy

Release Notes — Format & Structure Guide ​

Repository Structure ​

Deploy ​

Page Types ​

1. Individual Release Page (releases/<version>/index.html) ​

Structure ​

When all items share the same PR ​

When items have different PRs ​

Section label classes ​

2. Monthly Overview Page (YYYY-MM/index.html) ​

Structure ​

Filter pills ​

Feature card ​

Badge classes ​

Feature icon ​

Meta Block — Required Fields ​

Author HTML ​

Reviewer HTML (same but dimmed) ​

Known contributors ​

PR link HTML ​

Landing Page (index.html) ​

Monthly overview card ​

Individual release card ​

Checklist — New Individual Release ​

Checklist — New Monthly Overview ​

Release Notes — Format & Structure Guide

Repository Structure

Deploy

Page Types

1. Individual Release Page (`releases/<version>/index.html`)

Structure

When all items share the same PR

When items have different PRs

Section label classes

2. Monthly Overview Page (`YYYY-MM/index.html`)

Structure

Filter pills

Feature card

Badge classes

Feature icon

Meta Block — Required Fields

Author HTML

Reviewer HTML (same but dimmed)

Known contributors

PR link HTML

Landing Page (`index.html`)

Monthly overview card

Individual release card

Checklist — New Individual Release

Checklist — New Monthly Overview